| Sun ONE Portal Server 6.1 Administrator's Guide |
Appendix H
Open Web Application InterfaceSun ONE Portal Server 6.1 is an extensible web application. Unfortunately, the definition of web applications in the Java 2 Enterprise Edition (J2EE) specification does not specify how a web application can be extended, while at the same time maintaining the ability for a vendor to provide updates to the product software. One of the reasons is to allow any file to be added to the Sun ONE Portal Serverweb applicationm.
With the Sun ONE Portal Server open web application file interface, users are allowed to modify the files that are shipped with the system The Sun ONE Portal Server open web application file interface consists of the following conventions to customize the Sun ONE portal software:
- Sun ONE Portal Server 6.1 extensions made by developers or users may add files to the $BASEDIR/SUNWps/web-src directory as desired. Any file named with a -x in the name is guaranteed to not conflict with any file that is ever added to the Sun ONE Portal Server in the future by Sun Microsystems.
- The files that are shipped as part of Sun ONE Portal Server must not be modified as they may be updated by a future portal server release. users may use the deploy command for installing changes to the web application.
Customizing JSPs for the Sun ONE Portal ServerJavaServer Pages (JSP) can be used with the Sun ONE Portal Server admin console within the Sun ONE Application Framework (JATO). One of the reasons for using JSP files in the implementation of an application is to permit the user to modify the JSP to change how the application is presented to the user. Modifications to JSP files are supported using a servlet mapping in the web application descriptor file, web.xml. By overriding this mapping, the user can then cause a customized JSP file to be used rather than the one shipped with the product.
For example, consider sample.jsp that is shipped with the product. The WEB-INF/xml directory would contain the following file to define the servlet mapping:
<web-app>
<servlet>
<servlet-name>sample</servlet-name>
<jsp-file>/sample.jsp</jsp-file>
</servlet>
<servlet-mapping>
<servlet-name>sample</servlet-name>
<url-pattern>/sample</url-pattern>
</servlet-mapping>
</web-app>
Any HTML or JSP files that need to present a link to sample.jsp uses the /sample URI, and not /sample.jsp. There must be no references to sample.jsp anywhere other than in the sample.xml file.
To create a customized version of sample.jsp, the user would add the file sample-x.jsp by making a copy of sample.jsp. Note the use of the -x convention to avoid filename conflicts. The user would also add a file to the WEB-INF/xml directory as follows:
<web-app>
<servlet>
<servlet-name>sample</servlet-name>
<jsp-file>/sample-x.jsp</jsp-file>
</servlet>
</web-app>
The filename sample-x.xml is alphabetically after sample.xml, so when the deploy command merges these files to form the web.xml file, this definition for the servlet will override the one in sample.xml. Therefore, the user will see the customized file rather than the one shipped with the product.
Customizing the Properties Files
To customize a resource bundle properties file, the user would need to define a locale variant according to the specification in the Java Locale class. or example, say that a developer wanted to define special values for certain properties in the sample.properties file. For the English, United States locale, a file would be created called sample_en_US_Sun-x.properties with only the values that are being changed. A similar file would need to be created for every other locale that is to be supported too. The preferred locale for users in the directory would need to be changed to en_US_Sun-x so that this new file would be picked up by the portal server.
Hiding Portal Content
Users may want to prevent access to parts of the Sun ONE Portal Server (such as Javadoc pages). This is done by defining additional servlet mappings using a new web.xml fragment. For example, the following fragment will redirect access to anything under the /javadocs directory to a noaccess-x.jsp file that can return an error code or message:
<web-app>
<servlet>
<servlet-name>noaccess</servlet-name>
<jsp-file>/noaccess.jsp</jsp-file>
</servlet>
<servlet-mapping>
<servlet-name>noaccess</servlet-name>
<url-pattern>/javadocs/*</url-pattern>
</servlet-mapping>
</web-app>
Deploy Command and ClustersWeb application deployment on application server clusters supports automatic copying of the web application to multiple servers for some application servers, so the instructions regarding use of the Portal Server deploy command need to accommodate this:
/opt/SUNWps/bin/deploy [redeploy]
The deploy command packages the source files for the Sun ONE Portal Server web application files and deploys the package to the web container that hosts the portal server software. See Command-Line Utilities for more information.
For example, a suggested approach could be:
- Add changes to /opt/SUNWps/web-src on the first server.
- Deploy the web application on the first server
- Propagate the changes to /opt/SUNWps/web-src on the remaining servers.
- Deploy the web application from all servers.
- Log in to the application server admin console and deploy the Sun ONE Portal Server web application to all servers.
See the Sun ONE Portal Server 6.1 Installation Guide for more information about specific application server configuration.
Known Limitations
With this solution, the user is not able to make arbitrary changes to the Sun ONE Portal Server web application:
- The look and feel of the JSP files that are used in the admin console cannot be modified.
- Properties files cannot be updated (although they can be overridden by using a locale variant).
- JAR files shipped with the Sun ONE Portal Server cannot be modified, although individual classes in those JAR files could be replaced by putting alternate versions of the class files in the WEB-INF/classes directory.
- Administrators can modify web.xml once an web application is deployed When redeploy occurs, these modifications will be lost.
