From portal-commits at lists.jboss.org Fri Feb 8 06:00:20 2008 Content-Type: multipart/mixed; boundary="===============3226935016652999117==" MIME-Version: 1.0 From: portal-commits at lists.jboss.org To: portal-commits at lists.jboss.org Subject: [portal-commits] JBoss Portal SVN: r9869 - docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules. Date: Fri, 08 Feb 2008 05:56:20 -0500 Message-ID: --===============3226935016652999117== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: thomas.heute(a)jboss.com Date: 2008-02-08 05:56:20 -0500 (Fri, 08 Feb 2008) New Revision: 9869 Modified: docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/configuration.xml docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/installation.xml docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/migration.xml docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/tutorials.xml Log: Merge with Branch_2_6 Modified: docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/configurat= ion.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/configuration.xm= l 2008-02-08 10:45:01 UTC (rev 9868) +++ docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/configuration.xm= l 2008-02-08 10:56:20 UTC (rev 9869) @@ -46,44 +46,22 @@ - Changing the context path - By default, the "main" page of JBoss portal will be accessible= at - http://localhost:8080/portal/index.html - . You may want to change that - either to a different name or to - http://localhost:8080/index.html - . - - - By default, Tomcat holds on to the root context '/'. You may need= to either remove - $JBOSS_HOME/server/default/deploy/jboss-web.deployer/ROO= T.war - or add a jboss-web.xml file (declaring another= context-root other than '/') under - ROOT.war/WEB-INF directory for the below chang= es to take effect on restart. - - - /tomcat-root -]]> - - You can accomplish this, with either a deployed jboss-portal.s= ar or before you build from source: - - - - Binary method: - - - Open - - JBOSS_INSTALL_DIRECTORY/server/default/deplo= y/jboss-portal.sar/portal-server.war/WEB-INF/jboss-web.xml - + Changing the Context Path + By default, the main JBoss Portal page is accessible by naviga= ting to http://localhost:8080/portal/index.html. This +can be changed to a different path, for example, +http://localhost:8080/index.html. The context path ca= n be changed when using the deployed jboss-portal.sar/= , or before building from source. To change the context path when using the= JBoss Portal binary package: + + + + + Open the $JBOSS_HOME/server/default/depl= oy/jboss-portal.sar/portal-server.war/WEB-INF/jboss-web.xml file= . If this file does not exist, copy and save the following example: java:jaas/portal /portal - SET_AND_GET - SYNC + SET jdbc/PortalDS @@ -94,121 +72,185 @@ Edit the - context-root - element to whatever you desire. - /]]> - + <context-root> element with the desired context path: + + + +/testing]]> + + + + Using this example, the main JBoss Portal page would be reached by nav= igating to http://localhost:8080/testing. + - + + To change the context path when building from source: + + + - Source method: - Edit the file - $PORTAL_HOME/build/local.properties - (You can copy the file - $PORTAL_HOME/build/etc/local.properties-example= - and modify it for your - own settings.) and change - portal.web.context-root - to anything you want. - Now clean the project (ant clean) then build JBoss= portal (ant) and redeploy it for the context - path changes to take - effect. For build instructions, please see: - - - - - - + Change into the directory where the JBoss Portal Source= Code zip file was extracted to, or where the source from SVN wa= s checked out to. Copy the build/etc/local.properties-example file and save it as build/local.properties. + + + + + Open the build/local.properties file and edit the= portal.web.context-root option with the d= esired context path: + + + +# Context root for the portal main servlet +portal.web.context-root=3D/testing + + + + Using this example, the main JBoss Portal page would be reached by nav= igating to http://localhost:8080/testing. + + + + = + + To clean the project, make sure you are connected to the Internet, and= change into the build/ directory. Run the an= t clean command. + + + + + Re-build and re-deploy JBoss Portal. See for build instructions. + + + + + + + + By default, Tomcat holds on to the root context, /. You may need to remove the $JBOSS_HOME/server/default/de= ploy/jboss-web.deployer/ROOT.war/ directory, + or add a jboss-web.xml file, which declares = another + context-root other than /, under the $JBOSS_HOME/server/default/deploy/jboss-web.deployer/ROOT.war/WEB-INF/ directory, for the above changes to take affect. The following is= an example jboss-web.xml file, which changes the Tomc= at context path to /tomcat-root: + + + + + /tomcat-root +]]> + + + - Forcing the DB dialect - If you encounter that the Hibernate dialect is not working pro= perly and would like to - override the default behavior, follow the instructions contained = in this section: - Under most common circumstances, the auto-detect feature sh= ould work fine. + Forcing the Database Dialect + + This sections describes how to override the Database (DB) dialect s= ettings. Under most circumstances, the auto-detect feature will work. If th= e Hibernate dialect is not working correctly, override the default behavior= by following the instructions in this section. - DB Dialect settings for Portal - You will need to modify all the hibernate.cfg.xml<= /literal> files in all the Portal modules you - intend to use by uncommenting the following line in these file= s and using the appropriate dialect (see - here - for a list of supported dialects in Hibernate 3): - Database Dialect Settings for JBoss Portal + + All hibernate.cfg.xml files in all JBoss Portal mo= dules you intend to use need to be modified. The hibernate.cfg.xm= l files are found in the jboss-portal.sar/module/conf/hibernate/directory/<= /filename> directory, where module is the module= name, and directory is a directory that, depend= ing on the module, may or may not exist. + + + To modify these files to force the DB dialect, un-comment the following= line from each hibernate.cfg.xml file in each JBoss P= ortal module you intend to use, so that it looks like the following: + + + -]]> - - These files are found in jboss-portal.sar/[module]= /conf/hibernate/[directory]/hibernate.cfg.xml - where [module] is a module name and [directory] is a directory that - may or may not be present. - +]]> + + + Note: this example is for a PostgreSQL database. If you use another data= base, you will need to modify org.hibernate.dialect.Postgre= SQLDialect to reflect the correct database. For a list of = supported dialects, refer to the dialects list on the Hibernate website. + - DB Dialect settings for the CMS component - Modify jboss-portal.sar/portal-cms.sar/conf/hibern= ate/cms/hibernate.cfg.xml by - uncommenting the following line in these files and using the a= ppropriate dialect (see - here - for a list of supported dialects in Hibernate 3): - DB Dialect Settings for the CMS Component + + To modify the DB dialect setting for the JBoss Portal CMS component: + + + + + + Open the jboss-portal.sar/portal-cms.sar/conf/hibernate/cm= s/hibernate.cfg.xml file. + + + + + Un-comment the following line, so that it looks like the following: + + + -]]> - +]]> + + + + + + Note: this example is for a PostgreSQL database. If you use another data= base, you will need to modify org.hibernate.dialect.Postgre= SQLDialect to reflect the correct database. For a list of = supported dialects, refer to the dialects list on the Hibernate website. + - Setting up the email service - To be able to use the email service (for example to verify use= r emails when someone subscribes or for CMS - workflow notifications) it has to be configured correctly. To config= ure it, go to - jboss-portal.sar/portal-core.sar/META-INF/jboss-service.xml= . - In this file, the mail module is configured like this: - - - jboss:service=3DMail - portal:service=3DModule,type=3DIdentityServiceController - -1 - localhost - - - false - 100000 - 10000 - java:portal/MailModule -]]> - Here you can specify a different SMTP server than localhost, then= precise the SMTP username and SMTP password to - use to send emails. - For example, to use GMail's SMTP server: - - - jboss:service=3DMail - portal:service=3DModule,type=3DIdentityServiceController - -1 - smtp.gmail.com - username(a)gmail.com - myPassword - false - 100000 - 10000 - java:portal/MailModule -]]> + Setting up the Email Service + + If you have a standard setup and a mail server installed, the email= service should work without any extra configuration. Most Linux distributi= ons have a mail server installed by default. The email service, for example= , can be used to verify a user's email address when a user subscribes, or f= or CMS workflow notifications. - If you have a 'standard' setup and a mail server install= ed - (That's the case on most Linux distribution out of the box), it will= work out of the box. - + + The email service is configured using the $JBOSS_HOME/ser= ver/default/deploy/jboss-portal.sar/META-INF/jboss-service.xml f= ile. The following is an example of the section which is used to configure = the email service: + + + + +jboss:service=3DMail +portal:service=3DModule,type=3DIdentityServiceController +-1 +localhost + + +false +100000 +10000 +java:portal/MailModule +]]> + + + + A different SMTP server (other than localhost) can be configured, along = with a SMTP username and an SMTP password. The following is an example conf= iguration that uses the Gmail SMTP server: + + + + +jboss:service=3DMail +portal:service=3DModule,type=3DIdentityServiceController +-1 +smtp.gmail.com +username(a)gmail.com +myPassword +false +100000 +10000 +java:portal/MailModule +]]> + + + + Using this example, replace username(a)gmail.com and myPassword with your correct= Gmail username and password. + + - Setting up proxy settings + Configuring proxy settings There are a couple of scenarios where you will need your proxy= to be correctly defined at the JVM level so that you can access documents from Internet. It could be to= get the thirdparty libraries if you decided to build JBoss Portal from the sources, to access RSS feeds = or weather information in the samples @@ -219,19 +261,24 @@ is enough. - Disabling dynamic proxy unwrapping - JBoss Portal use the JBoss Microkernel for the service infr= astructure. The JBoss Microkernel provides - injection of services into other services, also known as wiring. = Unfortunately it is only possible to inject - dynamic proxies that talks to the MBeanServer due to the fact the= Microkernel is JMX based. The overhead - at runtime is minimal since the Microkernel implementation is hig= hly optimized, however when it is used - with Java 5 a noticeable bottleneck appears due to the fact that = the implementation - of the JMX API classes javax.management.* pr= ovided by the Java Platform performs synchronization. This does - not happen under JDK 1.4 since those classes are implemented by J= Boss MX. - JBoss Portal services use a special kind of Model MBean cal= led JBossServiceModelMBean which allows to - unwrap the injected dynamic proxies and replace them by the real = POJO services. This allows to remove the - bottleneck with Java 5 and provide an extra boost of performances= on JDK 1.4. By default that feature - is enabled but it is possible to disabled it using command line a= rguments. - run.sh -Dportal.kernel.no_proxies=3Dfalse]]> + Disabling Dynamic Proxy Un-wrapping + JBoss Portal uses the JBoss Microkernel for the service infras= tructure. The JBoss Microkernel provides injection of services into other s= ervices, otherwise known as wiring. Due to the Microkernel being JMX based,= it is only possible to inject dynamic proxies that talk to the MBeanServer= . The overhead at runtime is minimal since the Microkernel implementation i= s highly optimized; however, when it is used with Java 5, a noticeable bott= leneck occurs due to the fact that the implementation of the JMX API classe= s, javax.management.*, provided by the Java Platform, = perform synchronization. This does not occur under JDK 1.4, since those cla= sses are implemented by JBoss MX. + + + JBoss Portal services use a special kind of Model MBean called JBossServiceModelMBean, which allows the un-wrapping of inject= ed dynamic proxies, and replaces them with plain old java object (POJO) ser= vices. This removes the bottleneck when using Java 5, and also provides a p= erformance boost on JDK 1.4. By default this feature is enabled, but it is = possible to disable. To do this on Linux systems, change into the $JBOSS_HOME/bin/ directory and run the following command: + + + +./run.sh -Dportal.kernel.no_proxies=3Dfalse + + + + On Microsoft Windows systems, run the following command: + + + +run.bat -Dportal.kernel.no_proxies=3Dfalse + + Modified: docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/installati= on.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/installation.xml= 2008-02-08 10:45:01 UTC (rev 9868) +++ docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/installation.xml= 2008-02-08 10:56:20 UTC (rev 9869) @@ -25,7 +25,7 @@ - Start the server: change into = the JBOSS_PORTAL_INSTALLATION_DIRECTORY/bin/ directory= . On Microsoft Windows, execute run.bat. On Linux, run t= he ./run.sh command. + Start the server: change into = the JBOSS_PORTAL_INSTALLATION_DIRECTORY/bin/ directory= . On Microsoft Windows, execute run.bat. On Linux, run t= he ./run.sh command. To specify a configuration to use, = for example, the default configuration, append the -c default option to the run.bat or ./run.sh commands. @@ -125,7 +125,7 @@ - Copy the Datasource descriptor that matches your database into th= e $JBOSS_HOME/server/configuration/dep= loy/ directory, where configuration i= s either all, default or minimal. For example, if you are using the all con= figuration, copy the Datasource descriptor into the $JBOSS_HOME/s= erver/all/deploy/ directory. + Copy the Datasource descriptor that matches your database into th= e $JBOSS_HOME/server/configuration/dep= loy/ directory, where configuration i= s either all, default, minimal or production. The production configuration = only exists on JBoss EAP, and not JBoss AS. For example, if you are using t= he all configuration, copy the Datasource descriptor into the $JB= OSS_HOME/server/all/deploy/ directory. After the Datasource descriptor has been copied into the deploy directory, make sure the username, password, connection= -url, and driver-class are correct for your chosen database. Datasource des= criptor files can be deployed to test before being used in production. The = following is an example Datasource descriptor for the PostgreSQL database: @@ -161,7 +161,7 @@ - Start the server: change into the <= filename>$JBOSS_HOME/bin/ directory. On Microsoft Windows, execu= te run.bat. On Linux, run the ./run.sh command. + Start the server: change into the <= filename>$JBOSS_HOME/bin/ directory. On Microsoft Windows, execu= te run.bat. On Linux, run the ./run.sh command. To specify a configuration to use, for example, the default conf= iguration, append the -c default option to the run.bat or ./run.sh commands. @@ -348,7 +348,7 @@ Replace proxy-hostname with the proxy server= 's hostname, and proxy-port with the correct pro= xy server port number. - To build and deploy JBoss Portal from the sources, change into the= JBOSS_PORTAL_HOME_DIRECTORY/build/ directory. Then, = Microsoft Windows users need to run the build.bat deploy= command, and Linux users need to run the ./build.sh deploy command. + To build and deploy JBoss Portal from the sources, change into the = JBOSS_PORTAL_SOURCE_DIRECTORY/build/ directory, where= JBOSS_PORTAL_SOURCE_DIRECTORY is the directory where = the JBoss Portal source code was downloaded to. Then, Microsoft Windows use= rs need to run the build.bat deploy command, and Linux u= sers need to run the ./build.sh deploy command. At the end of the build process, the jboss-portal.sar file is copied into the $JBOSS_HOME/server/default/deploy/ directory: @@ -375,7 +375,7 @@ - Change into the JBOSS_PORTAL_HOME_DIRECTORY/build/ directory, and run the following command: + Change into the JBOSS_PORTAL_SOURCE_DIRECTORY/build/ directory, and run the following command: @@ -385,7 +385,7 @@ - Change into the JBOSS_PORTAL_HOME_DIRECTORY/core/ directory, and run the following command: + Change into the JBOSS_PORTAL_SOURCE_DIRECTORY/core/ directory, and run the following command: @@ -441,7 +441,7 @@ - Copy the Datasource descriptor that matches your database into the $JBOSS_HOME/server/configuration/deploy/<= /filename> directory, where configuration is eit= her all, default, minimal, or production. For example, if you are using the= production configuration, copy the Datasource descriptor into the $JBOSS_HOME/server/production/deploy/ directory. + Copy the Datasource descriptor that matches your database into the $JBOSS_HOME/server/configuration/deploy/<= /filename> directory, where configuration is eit= her all, default, minimal, or production. For example, if you are using the= production configuration, copy the Datasource descriptor into the $JBOSS_HOME/server/production/deploy/ directory. The productio= n configuration only exists on JBoss EAP installations, and not JBoss AS. After the Datasource descriptor has been copied into the dep= loy directory, make sure the username, password, connection-url,= and driver-class are correct for your chosen database. Datasource descript= or files can be deployed to test before being used in production. The follo= wing is an example Datasource descriptor for the PostgreSQL database: @@ -477,7 +477,7 @@ - Start the server: change int= o the $JBOSS_HOME/bin/ directory. On Microsoft Windows= , execute run.bat. On Linux, run the ./run.sh command. + Start the server: change int= o the $JBOSS_HOME/bin/ directory. On Microsoft Windows= , execute run.bat. On Linux, run the ./run.sh command. To specify a configuration to use, for example, the defau= lt configuration, append the -c default option to the <= command>run.bat or ./run.sh commands. Modified: docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/migration.= xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/migration.xml 20= 08-02-08 10:45:01 UTC (rev 9868) +++ docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/migration.xml 20= 08-02-08 10:56:20 UTC (rev 9869) @@ -11,124 +11,134 @@ boleslaw dot dawidowicz at redhat dot com - Upgrading 2.4 - 2.6 + Upgrading JBoss Portal 2.4 to 2.6 + - Before performing any instructions or operations mentioned below rem= ember to backup your database content and - the whole application server directory! + + Before performing any instructions or operations in this chapter, back u= p your database content and + the entire JBoss EAP or JBoss AS directory! + + - Manual upgrade + Manual Upgrade - Although database schema remains the same in JBoss Portal 2.6 the= re are several differences that prevent from simple deployment - of newest portal version using JBoss Portal 2.4 database. In this= chapter we will list major ones and give - instructions on how to manually update proper data. + Although the database schema remains the same in JBoss Portal 2.6= , there are several differences that prevent simply deploying the latest ve= rsion of JBoss Portal, when using a database created for JBoss Portal 2.4. = This chapter describes updating a JBoss Portal 2.4 MySQL database for use w= ith JBoss Portal 2.6. - Upgrading procedure can be quite straightforward: - + The upgrade procedure can be straightforward: + + + - Remove $JBOSS_HOME/server/default/d= eploy/jboss-portal.sar file. + + If you are using the JBoss Portal binary, remove the $JBOSS_H= OME/server/default/deploy/jboss-portal.sar/ directory. If JBoss = Portal was built from source, remove the $JBOSS_HOME/server/defau= lt/deploy/jboss-portal.sar file. + - Update data in portal database like described in following = sections of this chapter + + Update the data in the JBoss Portal database, as described in . + - Deploy JBoss Portal 2.6 + + Deploy JBoss Portal 2.6. + - + - Theme + Themes + + Themes in JBoss Portal 2.6 have changed since the Portal pages now cont= ain additional areas, such as the Login, Admin<= /guiicon>, and Dashboard links, on the top right-hand co= rner: + + + - Themes in 2.6 version changed as now they - contain additional areas - the best example is upper right cor= ner where links like "Login", "Admin", "My Dashboard" - are visable. If you use default theme like "renaissance" that = is present in 2.6, you shouldn't need to do anything. To update your custom= themes please - refer to those bundled with portal as an example. - - If you stay with old theme files you may find JBP 2.6 unusa= ble to the point that you may not even be able to log in + If you use a default theme that exists in JBoss Portal 2.6, such as ren= aissance, no configuration should be necessary. Using old themes from JBoss= Portal 2.4 may make JBoss Portal 2.6 unusable, for example, not being able= to log in. To update custom themes, please refer to those bundled with JBo= ss Portal as an example. + - - Database - All things described in this section can be done using Admi= nPortlet. Treat this directions more as guideline - if you need to automate migration for big portal deployment. + + Updating the Database - Database schema wasn't changed between 2.4 and 2.6 releases, b= ut still content that is kept in it - changed slightly in few areas. You can easily update the data = manually by using tools proper for your - RDBMS. If you use MySQL you can use MySQL Query Browser that can - be downloaded from MySQL website. + All procedures described in the following sections can performed using = the AdminPortlet. Treat the directions as guidelines if you need to automat= e the migration of a large JBoss Portal deployment. + + + Database schema has not changed between the JBoss Portal 2.4 and 2.6 re= leases, but certain content that is kept in the databases has changed. Data= can be updated manually by using the correct tools for your RDBMS. For exa= mple, if you are using a MySQL database, you can use the MySQL Query Browser. - - Instructions below refer to standard JBoss Portal 2.4 deployme= nt. If you named core portlets, portlet instances - or portlet windows differently you will need to make proper mo= difications in those steps. - + + The following instructions refer to a standard JBoss Portal 2.4 deploym= ent. If you named core portlets, portlet instances, or portlet windows diff= erently, you will need to make the appropriate modifications. The following= is an example of using the MySQL Query Browser: + + - - Portlet names - Names of few core bundled portlets changed. To update th= em you need to: + + + + Portlet Names - In JBP_INSTANCES table: - - Change "local.portal.CMSPorlet" in PORTLET_REF column to - "local./portal-cms.CMSPortlet" - - Change "local.portal.CMSAdminPorlet<= /emphasis>" in PORTLET_REF column to - "local./portal-cms.CMSAdminPortlet" - - Change "local.portal.ManagementPorle= t" in PORTLET_REF column to - "local./portal-admin.AdminPortlet" - - - - Instead of editing database you can destroy those instan= ces in AdminPortlet and recreate them. + Names of certain core bundled portlets have changed. Destroy the fol= lowing instances and use the AdminPortlet to recreate them, or, edit the JBP_INSTANCES table as follows: + + + + + + Change local.portal.CMSPorlet in the PORTLET_REF column to local./portal-cms.CMSPortlet= . + + + + + Change local.portal.CMSAdminPorlet in the PORTLET_REF column to local./portal-cms.CMSAdm= inPortlet. + + + + + Change local.portal.ManagementPorlet in the = PORTLET_REF column to local./portal-admin.Ad= minPortlet. + + + + - NavigationPortlet from JBP 2.4 is not = present anymore. Its functionality is now realized by - PageCustomizerInterceptor so all refer= ences to NavigationPortlet should - be removed from all portal pages. You can do it either by c= leaning up database content or by using - AdminPortlet in Portal interface. In d= atabase you should remove: - - - Rows containing "local.portal.NavigationPor= tlet" in - "PORTLET_REF" column in - "JBP_INSTANCES" table. - - - Rows containing "NavigationPortletInstance<= /emphasis>" in - "INSTANCE_REF" column in - "JBP_WINDOW" table. - - - Rows containing "NavigationPortletWindow" in - "NAME" column in - "JBP_OBJECT" table. - - - - Instead of editing database you can just remove Navigati= onPortletInstance using AdminPortlet. - - + The NavigationPortlet from JBoss Portal 2.4 has= been removed, and its functionality is now replaced by PageCusto= mizerInterceptor. All references to the NavigationPort= let should be removed from all portal pages. Remove Na= vigationPortletInstance using the AdminPortlet, or edit the data= base as follows: + + + + + + In the JBP_INSTANCES table, rows containing= local.portal.NavigationPortlet in the PORTL= ET_REF column. + + + + + In the JBP_WINDOW table, rows containing NavigationPortletInstance in the INSTANCE_REF<= /emphasis> column. + + + + + In the JBP_OBJECT table, rows containing NavigationPortletWindow in the NAME= column. + + + + + + CMS - This is probably the less trival part to do directly in dat= abase. In JBP 2.6 version the way that CMS - content is being displayed changed significantly. Please re= fer to - Content Integration and CMS Portlet - chapters for more information. Basically currently there is= no need to have more than one instance of - CMSPortlet and the portlet window disp= lays CMS content not by referring to that portlet instance - but by having proper content-type defi= ned. In "default-object.xml - you will find following configuration: - - and . Currently th= ere is no need to have more than one instance of the CMSPortlet. The portlet window displays CMS content, not by referring to tha= t portlet instance, but by having the proper content-type defined. The following configuration is in the jboss-portal.s= ar/conf/data/default-object.xml file: + + + CMSWindow @@ -137,53 +147,53 @@ center 0 - - ]]> - +]]> + + + + The following example uses the MySQL Query Browser. Open the JBP_OBJECT_NODE table in your database schema. = Look at the PATH column to identify any = occurrences of CMS in your JBoss Portal deployment. Identify any row referr= ing to CMSPortletWindow, and remember the number in PK column. The PK<= /emphasis> number is needed in the following steps: - Open JBP_OBJECT_NODE tab= le in your database schema. By looking at - PATH column you will eas= ily find any occurances of CMS in your portal - deployment - + - For any row you will identify as referring to CMS= PortletWindow in your system remember - the number in PK column.= It will be needed in next steps + Go to the JBP_WINDOW table and fi= nd a row with the same + PK value from the JBP_OBJECT_NODE table. In such a row, replace CMSPortletInstance with a path to your CMS resource. For examp= le, by default, JBoss Portal displays /default/index.html. - Go to JBP_WINDOW tab= le and find row with the same - PK value like the one fr= om - JBP_OBJECT_NODE table. I= n such row replace - "CMSPortletInstance" with a path to yo= ur CMS resource. For example by default - portal is displaying "/default/index.html". - - Go to JBP_PORTAL_OBJECT_PROPS table and add a row containing: + Go to the JBP_PORTAL_OBJECT_PRO= PS table and add a row containing: - The number you remembered in "OBJECT_KEY" column. - - - "portal.windowContentType" in "<= emphasis>NAME" column. - - - "cms" in "jbp_VALUE" column. - - - + + The PK number remembered from the= OBJECT_KEY column. + + + + + portal.windowContentType in the NAME<= /emphasis> column. + + + + + cms in the jbp_VALUE colum= n. + + + + - Remember that you can also change portlet window content= type and configure path to CMS resource - using AdminPortlet + + Portlet Content Type and Path to the CMS Resource + + You can change the portlet window content type and configure the path = to the CMS resource + using the AdminPortlet. + + - - - - - - + + = - Deploying your first portlet + Deploying your First Portlet Introduction - This section will introduce the reader to deploying his = first portlet in JBoss Portal. It requires you - download the HelloWorldPortlet from PortletSwap.com, using = this - link. - + + This section details deploying your first portlet in JBoss Portal. B= efore proceeding, download the HelloWorldPorlet from JBoss PortletSwap. + Package Structure - Portlets are packaged in WAR files, just like other JEE app= lications. A typical portlet WAR file can also - include servlets, resource bundles, images, HTML, JSPs, and= other static or dynamic files you would - commonly include. + Like other Java EE applications, portlets are packaged in W= AR files. A typical portlet WAR file can include servlets, resource bundles= , images, HTML, JSPs, and other static or dynamic files. The following is a= n example of the directory structure of the HelloWorldPortlet portlet: @@ -141,15 +159,16 @@ - Portlet Class + Portlet Classes - Included in the - - download bundle you should have one java source = file: - HelloWorldPortlet\src\main\org\jboss\portlet\hello= \HelloWorldPortlet.java, and it - should contain the following: - HelloWorldPortlet/src/main/org/jboss/= portlet/hello/HelloWorldPortlet.java java source file, which com= es bundled with the HelloWorldPortlet: + + + - - Now let's dissect our simplest of portlets: - - - - public class HelloWorldPortlet ext= ends GenericPortlet - All Portlets MUST implement the javax.por= tlet.Portlet interface. The Portlet - API also provides a convenience implementation of = this interface in the form of the - javax.portlet.GenericPortlet cl= ass which, among other things, implements + protected void doView(RenderRequest rRequest, RenderResponse rResponse) = + throws PortletException, IOException, UnavailableException + + { + rResponse.setContentType("text/html"); + PrintWriter writer =3D rResponse.getWriter(); + writer.write("Hello World!"); + writer.close(); + } + +} ]]> + + + + + +public class HelloWorldPortlet extends GenericPortlet + + + All portlets must implement the javax.por= tlet.Portlet interface. The portlet + API provides a convenient implementation of this i= nterface, in the form of the + javax.portlet.GenericPortlet cl= ass, which among other things, implements the Portlet render method to di= spatch to abstract mode-specific methods to - make it easier to support the standard portlet mod= es. It also provides - a default implementation for processActio= n, init and - destory methods. It is recommen= ded to extend GenericPortlet + make it easier to support the standard portlet mod= es. As well, it provides + a default implementation for the processA= ction, init and + destroy methods. It is recommen= ded to extend GenericPortlet for most cases. - - - - - protected void doView(RenderReques= t rRequest, RenderResponse rResponse) throws - PortletException, IOException, UnavailableExcep= tion - As we extend from GenericPortlet and we are only interested in supported the - VIEW mode, we only need to impl= ement the doView method, - and GenericPortlet's r= ender implementation will call our - implementation when the VIEW mo= de is requested. - - - - - rResponse.setContentType("text/htm= l"); - Just like in the servlet-world, you must declare w= hat content-type the portlet will be - responding in. You need to do this before starting= to write content or the portlet will throw - an exception. - - - - - - Here we output the text - Hello World! - in our portlet window. - - Portlets are responsible for generating markup = fragments, as they are included on a page and - surrounded by other portlets. In particular, th= is means that a portlet outputting HTML MUST - not output any markup that cannot be found in a= body element. - - - - - + + + + +protected void doView(RenderRequest rRequest, RenderResponse rResponse) = +throws PortletException, IOException, UnavailableException + + + As we extend from GenericPortlet, and are only int= erested in supporting the VIEW mode, only the d= oView method needs to be implemented, and the GenericPor= tlet render implemention calls our implementat= ion when the VIEW mode is requested. + + + + +rResponse.setContentType("text/html"); + + + As in the servlet-world, you must declare what content-type the portl= et will be + responding in. Do this before starting to write content, or the portl= et will throw an exception. + + + + +PrintWriter writer =3D rResponse.getWriter(); = +writer.write("Hello World!"); = +writer.close(); + + + This produces the Hello World! text in our portlet= window. + + + + + + + + + Portlets are responsible for generating markup fragments, as they are i= ncluded on a page and are + surrounded by other portlets. In particular, this means that a portlet = outputting HTML must + not output any markup that cannot be found in a <body> element. + + + Application Descriptors - JBoss Portal requires certain descriptors be included in yo= ur portlet WAR, for different reasons. Some of - these descriptors are defined by the Portlet Specification,= some are specific to JBoss Portal. + JBoss Portal requires certain descriptors to be included in= a portlet WAR file. Some of + these descriptors are defined by the JSR-168 Portlet Specification= , and others are specific to JBoss Portal. The following is an example of t= he directory structure of the HelloWorldPortlet portlet: + + - Now let's explain what each of these does: - - - portlet.xml - + + + The following is an example of the HelloWorldPortlet/WEB-IN= F/portlet.xml file. Note: in order to create the WEB-I= NF and META-INF directories, extract the helloworldportlet.war file: + + + HelloWorld Portlet -]]> - This file must adhere to its definition in the Por= tlet Specification. You may define more than - one portlet application in this file. - - - - He= lloWorldPortlet]]> - Define your portlet name. It does not hav= e to be the Class name. - - - - - o= rg.jboss.portlet.hello.HelloWorldPortlet]]> - The Fully Qualified Name (FQN) of your po= rtlet class must be declared here. - - - - - - text/html - VIEW -]]> - The supports element a= llows you to declare all the markup types your - portlet supports in the render method. This is accomplish via the - mime-type element, whi= ch is required for every - portlet. Of course, the declared MIME typ= es must match the capability of the portlet. - - It also allows you to pair - which modes and window states are support= ed for each markup type. In out case, as all - portlets must support the VIEW portlet mo= de, we didn't have to declare it. We did need - to declare that our portlet supports the = text/html markup type. - Hence, we are letting the portal know tha= t it will be outputting text/html and - only support a VIEW mode. - - - - - - HelloWorld Portlet - -]]> - The portlet's title will be displayed as = the header in the portlet window, when - rendered, unless it is overridden program= matically. - - - - - - - portlet-instances.xml - +]]> + + + + This file must adhere to its definition in the JSR-168 Portlet Specifica= tion. You may define more than one portlet application in this file. + + + + HelloWorldPortlet]]> + + + Define the portlet name. It does not have to be the Class name. + + + +org.jboss.portlet.hello.HelloWorldPortlet]]= > + + + The Fully Qualified Name (FQN) of your portlet class must be declared he= re. + + + + + text/html + VIEW +]]> + + + The <supports> element allows you to declare al= l the markup types your + portlet supports in the render method. This is accomp= lished via the + <mime-type> element, which is required for ever= y portlet. The declared MIME types must match the capability of the portlet. + + + As well, it allows you to pair which modes and window states are support= ed for each markup type. All portlets must support the VIEW portlet mode, s= o this does not have to be decared. Define which markup type your porlet su= pports, which in this examepl is text/html. This section= tells the portal that it will only output text and HTML, and that it only = supports the VIEW mode. + + + + + HelloWorld Portlet +]]> + + + When rendered, the portlet's title will be displayed as the header in th= e portlet window, unless it is overridden programmatically. In this example= , the title would be HelloWorld Portlet. + + + + + + + The following is an example of the HelloWorldPortlet/WEB-INF/po= rtlet-instances.xml file: + + + @@ -314,17 +353,21 @@ HelloWorldPortlet -]]> - This is a JBoss Portal specific descriptor that al= lows you to create instances of portlets. The - portlet-ref value must match th= e portlet-name value - given in the packaged portlet.xml. The instance-id - value can be named anything, but it must match instance-ref values given - in *-object.xml files as we sha= ll below. - - - - helloworld-object.xml - +]]> + + + + This is a JBoss Portal specific descriptor that allows you to create inst= ances of portlets. The + <portlet-ref> value must match the <= portlet-name> value + given in the HelloWorldPortlet/WEB-INF/portlet.xml f= ile. The <instance-id> + value can be named anything, but it must match the instance-ref<= /literal> values given + in *-object.xml files as we shall below. + + + The following is an example helloworld-object.xml fi= le: + + + @@ -339,14 +382,18 @@ 1 -]]> +]]> + + + +*-object.xml files are JBoss Portal specific descriptor= s and allow users to +define the structure of their portal instances as well as create/configure= their windows and +pages. In our example, we create a portlet window, specify that it will di= splay the markup +generated by the HelloWorldPortletInstance portlet inst= ance, assign it to the +default.default page, and specify where it should appea= r on that page. + + = - *-object.xml files are JBoss Po= rtal specific descriptors and allow users to - define the structure of their portal instances as = well as create/configure their windows and - pages. In our example, we create a portlet window,= specify that it will display the markup - generated by the HelloWorldPortletInstanc= e portlet instance, assign it to the - default.default page, and speci= fy where it should appear on that page. - @@ -389,9 +436,7 @@ - - - + To illustrate the relationship between the descriptors, we = have provided this simple diagram @@ -426,6 +471,8 @@ ]]> + + = This declaration is equivalent to the previous example. We = specify that the content being displayed by the HelloWorldPortletWindow is a portlet content. The content URI @@ -433,7 +480,7 @@ It is possible to declare windows with a cms content type and use directly the path to the file in the CMS to make the window show the content of = the associated file. That behavior is pluggable and it is possible to plug virtually any kind of = content. - + = Building your portlet --===============3226935016652999117==--