Update portlet documentation for OSGi portlets

7 files changed, 138 insertions, 163 deletions

diff --git a/documentation/portal/chapter-portal.asciidoc b/documentation/portal/chapter-portal.asciidoc
index 269a538419..f075481885 100644
--- a/documentation/portal/chapter-portal.asciidoc
+++ b/documentation/portal/chapter-portal.asciidoc
@@ -7,11 +7,11 @@
 
 include::portal-overview.asciidoc[leveloffset=+2]
 
-include::portal-eclipse.asciidoc[leveloffset=+2]
+include::portal-ui.asciidoc[leveloffset=+2]
 
-include::portal-liferay.asciidoc[leveloffset=+2]
+include::portal-osgi.asciidoc[leveloffset=+2]
 
-include::portal-ui.asciidoc[leveloffset=+2]
+include::portal-liferay.asciidoc[leveloffset=+2]
 
 include::portal-deployment.asciidoc[leveloffset=+2]
 
diff --git a/documentation/portal/portal-deployment.asciidoc b/documentation/portal/portal-deployment.asciidoc
index 7350fb0536..fec0fd4793 100644
--- a/documentation/portal/portal-deployment.asciidoc
+++ b/documentation/portal/portal-deployment.asciidoc
@@ -7,6 +7,10 @@ layout: page
 [[portal.deployment]]
 = Deploying to a Portal
 
+For OSGi portlets in Liferay 7, see
+<<dummy/../../../framework/portal/portal-osgi#portal.osgi.portlet,"Publishing a Portlet With OSGi">>.
+The text below applies mostly to non-OSGi portlets.
+
 To deploy a portlet WAR in a portal, you need to provide a
 [filename]#portlet.xml# descriptor specified in the Java Portlet API 2.0
 standard (JSR-286). In addition, you may need to include possible portal vendor
@@ -33,9 +37,6 @@ changes to the UI itself, but only the following:
 * Vaadin libraries installed to portal (optional)
 * Portal configuration settings (optional)
 
-The Vaadin Plugin for Eclipse creates these files for you, when you create a
-portlet project as described in <<portal-eclipse#portal.eclipse,"Creating a Generic Portlet in Eclipse">>.
-
 Installing the widget set and themes to the portal is required for running two or more Vaadin portlets simultaneously in a single portal page.
 As this situation occurs quite easily, we recommend installing them in any case.
 Instructions for Liferay are given in <<portal-liferay#portal.liferay,"Developing Vaadin Portlets for Liferay">> and the procedure is similar for other portals.
diff --git a/documentation/portal/portal-eclipse.asciidoc b/documentation/portal/portal-eclipse.asciidoc
deleted file mode 100644
index 9c7843d55e..0000000000
--- a/documentation/portal/portal-eclipse.asciidoc
+++ /dev/null
@@ -1,100 +0,0 @@
----
-title: Creating a Generic Portlet in Eclipse
-order: 2
-layout: page
----
-
-[[portal.eclipse]]
-= Creating a Generic Portlet in Eclipse
-
-*_This section has not yet been updated for Vaadin Framework 8._*
-
-Here we describe the creation of a generic portlet project in Eclipse. You can
-use the Maven archetypes also in other IDEs or without an IDE.
-
-For Liferay portlet development, you may instead want to use the Maven archetype
-or Liferay IDE to create the project, as described in
-<<dummy/../../../framework/portal/portal-liferay#portal.liferay,"Developing
-Vaadin Portlets for Liferay">>.
-
-[[portal.eclipse.vaadin]]
-== Creating a Project with Vaadin Plugin
-
-The Vaadin Plugin for Eclipse has a wizard for easy creation of generic portlet
-projects. It creates a UI class and all the necessary descriptor files.
-
-Creating a portlet project is almost identical to the creation of a regular
-Vaadin servlet application project. For a full treatment of the New Project
-Wizard and the possible options, please see
-<<dummy/../../../framework/getting-started/getting-started-first-project#getting-started.first-project.creation,"Creating
-the Project">>.
-
-. Start creating a new project by selecting from the menu "File > New > Project..."+
-//TODO Use ellipsis
-
-//&lt;?dbfo-need height="8cm" ?&gt;
-. In the [guilabel]#New Project# window that opens, select "Web > Vaadin 7 Project" and click [guibutton]#Next#.
-//&lt;?dbfo-need height="10cm" ?&gt;
-. In the [guilabel]#Vaadin Project# step, you need to set the basic web project
-settings. You need to give at least the project name, the runtime, select
-[guilabel]#Generic Portlet# for the [guilabel]#Deployment configuration#; the
-default values should be good for the other settings.
-
-ifdef::web[]
-+
-image::img/project-new-portlet-1.png[]
-endif::web[]
-
-+
-You can click [guibutton]#Finish# here to use the defaults for the rest of the
-settings, or click [guibutton]#Next#.
-
-. The settings in the [guilabel]#Web Module# step define the basic servlet-related
-settings and the structure of the web application project. All the settings are
-pre-filled, and you should normally accept them as they are and click
-[guibutton]#Next#.
-
-. The [guilabel]#Vaadin project# step page has various Vaadin-specific application
-settings. These are largely the same as for regular applications. Setting them
-here is easiest - later some of the changes require changes in several different
-files. The [guilabel]#Create portlet template# option should be automatically
-selected. You can give another portlet title of you want. You can change most of
-the settings afterward.
-
-+
-image::img/project-new-portlet-3.png[]
-
-[guilabel]#Create project template#:: Creates a UI class and all the needed portlet deployment descriptors.
-
-[guilabel]#Application name#:: The application name is used in the title of the browser window, which is
-usually invisible in portlets, and as an identifier, either as is or with a
-suffix, in various deployment descriptors.
-
-[guilabel]#Base package name#:: Java package for the UI class.
-
-[guilabel]#Application class name#:: Name of the UI class. The default is derived from the project name.
-
-[guilabel]#Theme name#:: Name of the custom portlet theme to use.
-
-[guilabel]#Portlet version#:: Same as in the project settings.
-
-[guilabel]#Portlet title#:: The portlet title, defined in [filename]#portlet.xml#, can be used as the
-display name of the portlet (at least in Liferay). The default value is the
-project name. The title is also used as a short description in
-[filename]#liferay-plugin-package.properties#.
-
-[guilabel]#Vaadin version#:: Same as in the project settings.
-
-
-
-+
-Finally, click [guibutton]#Finish# to create the project.
-
-. Eclipse may ask you to switch to J2EE perspective. A Dynamic Web Project uses an
-external web server and the J2EE perspective provides tools to control the
-server and manage application deployment. Click [guibutton]#Yes#.
-
-
-
-
-
diff --git a/documentation/portal/portal-liferay.asciidoc b/documentation/portal/portal-liferay.asciidoc
index dd4ea7d14d..f3a32372c6 100644
--- a/documentation/portal/portal-liferay.asciidoc
+++ b/documentation/portal/portal-liferay.asciidoc
@@ -1,34 +1,35 @@
 ---
 title: Developing Vaadin Portlets for Liferay
-order: 3
+order: 4
 layout: page
 ---
 
 [[portal.liferay]]
 = Developing Vaadin Portlets for Liferay
 
-*_This section has not yet been updated for Vaadin Framework 8._*
-
 A Vaadin portlet requires resources such as the server-side Vaadin libraries, a
-theme, and a widget set. You have two basic ways to deploy these: either
-globally in Liferay, so that the resources are shared between all Vaadin
-portlets, or as self-contained WARs, where each portlet carries their own
-resources.
-
-The self-contained way is easier and more flexible to start with, as the
-different portlets may have different versions of the resources. Currently, the
-latest Maven archetypes support the self-contained portlets, while with portlets
-created with the Vaadin Plugin for Eclipse only support globally deployed
-resources.
-
-Using shared resources is more efficient when you have multiple Vaadin portlets
-on the same page, as they can share the common resources. However, they must use
-exactly same Vaadin version. This is recommended for production environments,
-where you can even serve the theme and widget set from a front-end server. You
-can install the shared resources as described in <<portal.liferay.install>>.
+theme, and a widget set. You have three basic ways to deploy these: either
+globally in Liferay so that the resources are shared between all Vaadin
+portlets, as self-contained WARs where each portlet carries their own
+resources or as OSGi bundles in Liferay 7.
+
+For Liferay 7 and OSGi portlets, see <<dummy/../../../framework/portal/portal-osgi#portal.osgi,"OSGi Portlets on Liferay 7">>. This is the recommended approach when using Vaadin 8.1 or later and Liferay 7.
+Currently, the latest Maven archetype supports the OSGi approach.
+
+The material below applies mostly to non-OSGi portlets.
+
+== Developing Vaadin Portlets for Liferay 6.2
+
+In non-OSGi environments, the self-contained approach to static resources is
+easier and more flexible, as the different portlets may have different
+versions of the resources.
+
+Using shared resources is not recommended as it forces all portlets on a page
+to use the same Vaadin version and resources. If using this approach, you can
+install the shared resources as described in <<portal.liferay.install>>.
 
 At the time of writing, the latest Liferay release 6.2 is bundled with a version
-of Vaadin release 6. If you want to use Vaadin 7 portlets with shared resources,
+of Vaadin release 6. If you want to use Vaadin 8 portlets with shared resources,
 you first need to remove the old ones as described in <<portal.liferay.remove>>.
 
 [[portal.liferay.profile]]
@@ -118,6 +119,10 @@ Creation of Vaadin a Maven project is described in
 Vaadin with Maven">>. For a Liferay project, you should use the
 [literal]#++vaadin-archetype-liferay-portlet++#.
 
+Note: For creating Liferay 6.2 projects for Vaadin Framework 8.1, use the 8.0
+version of the archetype and then update the dependency versions for Vaadin
+Framework.
+
 [[portal.liferay.project.archetype-parameters]]
 === Archetype Parameters
 
@@ -164,9 +169,8 @@ long as you have a single portlet, but causes a problem if you have multiple
 portlets. To solve this, Vaadin portlets need to use a globally installed widget
 set, theme, and Vaadin libraries.
 
-__Liferay 6.2, which is the latest Liferay version at the time of publication of
-this book, comes bundled with an older Vaadin 6 version. If you want to use
-Vaadin 7, you need to remove the bundled version and install the newer one
+__Liferay 6.2 comes bundled with an older Vaadin 6 version. If you want to use
+Vaadin 8, you need to remove the bundled version and install the newer one
 manually as described in this chapter.__
 
 In these instructions, we assume that you use Liferay bundled with Apache
@@ -218,19 +222,19 @@ copy their contents to [filename]#tomcat-x.x.x/webapps/ROOT/html/VAADIN#.
 +
 [subs="normal"]
 ----
-[prompt]#$# [command]#unzip# path-to/vaadin-server-7.1.0.jar 'VAADIN/*'
+[prompt]#$# [command]#unzip# path-to/vaadin-server-8.1.0.jar 'VAADIN/*'
 ----
 
 +
 [subs="normal"]
 ----
-[prompt]#$# [command]#unzip# path-to/vaadin-themes-7.1.0.jar 'VAADIN/*'
+[prompt]#$# [command]#unzip# path-to/vaadin-themes-8.1.0.jar 'VAADIN/*'
 ----
 
 +
 [subs="normal"]
 ----
-[prompt]#$# [command]#unzip# path-to/vaadin-client-compiled-7.1.0.jar 'VAADIN/*'
+[prompt]#$# [command]#unzip# path-to/vaadin-client-compiled-8.1.0.jar 'VAADIN/*'
 ----
 
 
@@ -252,7 +256,7 @@ vaadin.widgetset=com.vaadin.server.DefaultWidgetSet
 
 # Theme to use
 # This is the default theme if nothing is specified
-vaadin.theme=reindeer
+vaadin.theme=valo
 ----
 
 The allowed parameters are:
@@ -266,7 +270,7 @@ application server; in Liferay with Tomcat it would be located at
 notation. If the parameter is not given, the default widget set is used.
 
 [parameter]#vaadin.theme#:: Name of the theme to use. If the parameter is not given, the default theme is
-used, which is [literal]#++reindeer++#.
+used, which is [literal]#++valo++#.
 
 
 
diff --git a/documentation/portal/portal-osgi.asciidoc b/documentation/portal/portal-osgi.asciidoc
new file mode 100644
index 0000000000..2c02edbbe1
--- /dev/null
+++ b/documentation/portal/portal-osgi.asciidoc
@@ -0,0 +1,63 @@
+---
+title: Portlet UI
+order: 3
+layout: page
+---
+
+[[portal.osgi]]
+= OSGi Portlets on Liferay 7
+
+IMPORTANT: The OSGi support as described above is currently being developed and only available in the Framework 8.1 prerelease versions, starting from 8.1.0.beta1.
+
+Lifeary 7 supports modular portlet development using OSGi, and enables e.g.
+using multiple different Vaadin versions in different portlets on a page. 
+
+For general OSGi considerations with Vaadin Framework such as packaging and
+bundle manifests, and how to publish static resources such as themes and
+widget sets, see
+<<dummy/../../../framework/advanced/advanced-osgi#advanced.osgi,"Vaadin OSGi Support">>.
+
+
+[[portal.osgi.portlet]]
+== Publishing a Portlet With OSGi
+
+Publishing an OSGi portlet on Liferay 7+ can be done in two ways: using
+annotations or using properties.
+
+Annotating a UI class with [interfacename]#@VaadinLiferayPortletConfiguration#
+(available in `vaadin-liferay-integration`) and making it an OSGi service of type
+[classname]#UI# is the easiest way to automatically publish the UI as a portlet
+and configure it to use the correct static resources.
+
+[source, java]
+----
+@Theme(MyTheme.THEME_NAME)
+@VaadinLiferayPortletConfiguration(name = "Vaadin.Tutorial.1", displayName = "Vaadin Tutorial App")
+@Component(service = UI.class)
+public class MyUI extends UI {
+  ...
+}
+----
+
+When using this approach, it is not necessary to create all the portlet
+property files that plain JSR-362 portlets require.
+
+Alternatively, the property [literal]#com.vaadin.osgi.liferay.portlet-ui=true#
+can be used when publishing a UI as an OSGi service to publish the UI as a portlet.
+
+[source, java]
+----
+@Theme(MyTheme.THEME_NAME)
+@Component(service = UI.class, property = {
+        "com.liferay.portlet.display-category=category.vaadin",
+        "javax.portlet.name=my.vaadin.app.app.1.0.0",
+        "javax.portlet.display-name=Tutorial Portlet",
+        "javax.portlet.security-role-ref=power-user,user",
+        "com.vaadin.osgi.liferay.portlet-ui=true"})
+public class MyUI extends UI {
+  ...
+}
+----
+
+An OSGi portlet should be packaged as a JAR with a proper OSGi bundle
+manifest, and deployed to a portal that has its required bundles installed.
diff --git a/documentation/portal/portal-overview.asciidoc b/documentation/portal/portal-overview.asciidoc
index 8368de1fe2..cba94bb234 100644
--- a/documentation/portal/portal-overview.asciidoc
+++ b/documentation/portal/portal-overview.asciidoc
@@ -7,12 +7,14 @@ layout: page
 [[portal.overview]]
 = Overview
 
-Vaadin supports running UIs as portlets in a portal, as defined in the JSR-286
-(Java Portlet API 2.0) standard. A portlet UI is defined just as a regular UI,
-but deploying to a portal is somewhat different from deployment of regular web
-applications, requiring special portlet descriptors, etc. Creating the portlet
-project with the Vaadin Plugin for Eclipse or a Maven archetype automatically
-generates the necessary descriptors.
+Vaadin Framework supports running UIs as portlets in a portal, as defined in
+the JSR-286 (Java Portlet API 2.0) standard. A portlet UI is defined just as a
+regular UI, but deploying to a portal is somewhat different from deployment of
+regular web applications, requiring special portlet descriptors, etc. Creating
+the portlet project with the Maven archetype automatically generates the
+necessary descriptors.
+
+Vaadin Framework also supports developing OSGi portlets for Liferay 7.
 
 In addition to providing user interface through the Vaadin UI, portlets can
 integrate with the portal to switch between portlet modes and process special
@@ -23,5 +25,3 @@ Vaadin especially supports the Liferay portal and the needed portal-specific
 configuration in this chapter is given for Liferay. Vaadin also has a special
 Liferay IPC add-on to enable communication between portlets.
 
-
-
diff --git a/documentation/portal/portal-ui.asciidoc b/documentation/portal/portal-ui.asciidoc
index 9983d8004c..4f5335a451 100644
--- a/documentation/portal/portal-ui.asciidoc
+++ b/documentation/portal/portal-ui.asciidoc
@@ -1,6 +1,6 @@
 ---
 title: Portlet UI
-order: 4
+order: 2
 layout: page
 ---
 
@@ -32,34 +32,19 @@ public class MyportletUI extends UI {
 }
 ----
 
-If you created the project as a Servlet 3.0 project, the generated UI stub
-includes a static servlet class annotated with [classname]#@WebServlet#, as
-described in
-<<dummy/../../../framework/getting-started/getting-started-first-project#getting-started.first-project.exploring,"Exploring
-the Project">>.
-
-
-----
-    @WebServlet(value = "/*", asyncSupported = true)
-    @VaadinServletConfiguration(productionMode = false,
-                                ui = MyportletUI.class)
-    public static class Servlet extends VaadinServlet {
-    }
-----
-
-This enables running the portlet UI in a servlet container while developing it,
-which may be easier than deploying to a portal. For Servlet 2.4 projects, a
-[filename]#web.xml# is created.
+For OSGi portlets in Liferay 7, use additional annotations as described in
+<<dummy/../../../framework/portal/portal-osgi#portal.osgi,"OSGi Portlets on Liferay 7">>.
 
 The portlet theme is defined with the [classname]#@Theme# annotation as usual.
 The theme for the UI must match a theme installed in the portal. You can use any
 of the built-in themes in Vaadin. If you use a custom theme, you need to
 compile it to CSS with the theme compiler and install it in the portal under the
-[filename]#VAADIN/themes# context to be served statically.
+[filename]#VAADIN/themes# context to be served statically, or use the OSGi
+portlet mechanisms to publish the theme.
 
 In addition to the UI class, you need the portlet descriptor files, Vaadin
 libraries, and other files as described later.
-<<figure.portal.helloworld.project>> shows the complete project structure under
+<<figure.portal.helloworld.project>> shows a complete project structure under
 Eclipse.
 
 [[figure.portal.helloworld.project]]
@@ -73,5 +58,27 @@ application will show as illustrated in <<figure.portal.helloworld>>.
 .Hello World Portlet
 image::img/liferay-helloworld.png[]
 
+[[portal.ui.servlet]]
+== Testing Portlet UIs as Servlets
+
+If a portlet does not use any specific portlet APIs, deploying it as a servlet
+can make testing it easier than deploying it to a portal.
+
+If you created the project as a Servlet 3.0 project, the generated UI stub
+includes a static servlet class annotated with [classname]#@WebServlet#, as
+described in
+<<dummy/../../../framework/getting-started/getting-started-first-project#getting-started.first-project.exploring,"Exploring
+the Project">>.
+
+Otherwise, the following snippet can be used.
+
+----
+    @WebServlet(value = "/*", asyncSupported = true)
+    @VaadinServletConfiguration(productionMode = false,
+                                ui = MyportletUI.class)
+    public static class Servlet extends VaadinServlet {
+    }
+----
+