Deploying Sun Java Studio Creator Apps

Introduction

The output of Creator should be a J2EE compatible webapp. J2EE is a platform specification that enables a compatible application to run on any compatible J2EE implementation regardless of the vendor, thus preventing vendor lock-in. However, Creator webapps depend upon a subset of J2EE commonly implemented by web servers like Sun Web Server 6.1 or Apache Tomcat 5, so they can also run in servers that implement a certain subset of J2EE. There are different versions of J2EE, two important ones currently are 1.4 and 1.3. As of 2004-08-13, Creator exported webapps rely on certain features in J2EE 1.4 that are not in 1.3, however, there are workarounds that are described on this page.

J2EE is an umbrella spec that consists of a collection of component Java specs. Two important component specs are the Servlet and JSP specs. In particular, the Servlet spec describes a web application, or "webapp", and WAR files.

• J2EE 1.4 contains the component specs Servlet 2.4 and JSP 2.0
• J2EE 1.3 contains the component specs Servlet 2.3 and JSP 1.2

So containers can be categorized into two groups based upon the version of the Servlet and JSP specs they support.

J2EE 1.4 group containers:

• Sun Java System Application Server 8 PE (also used as the bundled development container)
• Tomcat 5

J2EE 1.3 group containers:

• Sun Web Server 6.1
• Sun Application Server 7
• Tomcat 4
• BEA WebLogic 8.1

Deployment Details

The following sections provide details for actions that should be done within Creator and within your deployment container.

Creator Actions

Develop and test your app in Creator using the bundled development container. Find out which group, your container belongs to and proceed with the following Creator actions.

If your container falls in either the J2EE 1.4 or the 1.3 group, do the following:

• If your app uses web services, in Library Manager, right-click "Web Service Support"->"Modify Library Reference" and check "Deploy" on all listed jars. This will include these jars in the exported war.
• The steps below are no longer needed if you are running 2004Q2_patch2 or newer but if you are running an older version do the following:
  • Add these 4 missing apache libraries as follows:
    • Not required for Sun Java AppServer 8 because container (accidentally) has compatible versions.
    • "Project Navigator"->"Library Reference" node->"Create New Library Reference" called "JSF Support Workaround"
    • Change scope to "User"
    • "Add" then navigate to ${creator-install-directory}/modules/autoload/ext
    • Select these 4 jars: commons-beanutils.jar, commons-collections.jar, commons-digester.jar, commons-logging.jar (eg. on Windows use control-click)
    • "OK" to finish
  • If you are deploying to Sun Web Server, then check if a container specific deployment descriptor file for AS8 PE called META-INF/sun-web.xml file exists. If it exists then remove it, and later at deploy time, replace it with the Sun Web Server version of the deployment descriptor which happens to have the same name but different format. See below for further information about deploy time actions.

If your container falls in the J2EE 1.3 group, then in addition, you may need to do the following (probably fixed in the version after 2004Q2 Patch 3):

• Some containers do not recognize the web.xml/welcome-files/welcome-file/.
  For example, if your container is Sun Web Server 6.1, Sun App Server 7 (a guess), or Tomcat 4,
  • Create a new file index.jsp containing something like <jsp:forward page="faces/Page1.jsp">
  • Edit the web.xml file welcome-file-list/welcome-file to contain index.jsp

Finally, execute "Project Navigator"->"Export WAR File" which should create a portable WAR file that is ready to deploy.

Container Actions

Before deploying your exported WAR, check that your container supports JSTL (Java Standard Tag Library). Most production container products like Sun App Server and Sun Web Server already contain this, but some like Tomcat or JBoss currently do not. I believe JSTL will be a required part of J2EE 1.5 in the future. Add JSTL to your container, if it is missing:

• If J2EE 1.4 group, eg. Tomcat 5, use JSTL version 1.1: copy ${creator-install-directory}/modules/autoload/ext/{jstl.jar, standard.jar} to Tomcat common/lib
• If J2EE 1.3 group, eg. Tomcat 4, use JSTL version 1.0.x: copy jaxen-full.jar, jstl.jar, saxpath.jar, standard.jar to Tomcat common/lib. Obtain JSTL 1.0.x from http://jakarta.apache.org/taglibs/doc/standard-doc/intro.html.

Proceed to deploy your webapp by first configuring your container as needed. Please refer to your container documention for more information. For example, if you are using Sun App Server 8, you can use the admin console to configure any data sources that are needed by your application. You may also need to install JDBC drivers at this time. For example, for information on configuring Tomcat data sources, see:

• Tomcat 5: http://jakarta.apache.org/tomcat/tomcat-5.0-doc/jndi-datasource-examples-howto.html
• Tomcat 4: http://jakarta.apache.org/tomcat/tomcat-4.1-doc/jndi-datasource-examples-howto.html

Next, take the Creator exported WAR file from above and deploy it on your container using your container's provided tools. For example, for Sun Java System Application Server 8, you may use the Admin Console or NetBeans cobundle. This step often requires manually configuring server datasources and may require editing container-specific deployment descriptors, eg. WEB-INF/sun-web.xml or META-INF/context.xml. See container-specific documentation for more info.

Finally, open a browser to the web application deployed to your container. For example, a URL for an application deployed at the context-path /mywebapp might be http://localhost:8080/mywebapp.

Troubleshooting

• Can a simple project be deployed? First, create a new project and add a single button. Perform the steps above.
• Look at the container/server log file for clues to what is failing.

Known bugs that will be fixed in a future release:

• JSP Fragment files (*jspf) files may not work correctly if it contains certain entities.

-- EdwinGoei - 01 Oct 2004