Creating and Deploying the Servlet Web Archive

To read about setting up the Remote Server, as well as in depth instructions for deploying/re-deploying the web archive from scratch, please refer to Remote Server Configuration

Creating the Web Archive File from a Linux Command line

Complete the following steps in order to create a copy of the Web Archive(WAR) file. This process can be automated by running the Bash shell script

 https://www.sharedrecords.org/svn/sra/trunk/etc/create-war.sh

from the command line.

  • Configure the properties files. Point the etc/build.properties file to the correct paths / keywords. The admin username should be 'admin'. In the default installation of Sun App Server, the j2ee home should be /opt/SUNWappserver , and the wscompile directory should be /opt/SUNWappserver/bin. Put the correct administrative password into etc/admin-password.txt . Copy the etc/server.policy file to /opt/SUNWappserver/domains/domain1/config . This file dictates the permissions of the web application. Since sharedrecords will be creating and deleting files, we'll want this (more permissive) server policy file, instead of the default.
  • Configure the *.xml webservice configuration files for JAX-RPC (NOTE from JJ: I believe this step is no longer neccessary when using the Servlett only methods).
    • The most notable changes that need to take place are replacing every instance of "localhost" with the server's URL (in etc/config-wsdl.xml , etc/config-interface.xml , etc/webservices.xml and etc/org.sharedrecords.properties).
    • In org.sharedrecords.properties , comment out the "org.sharedrecords.OtherPropertyFiles?" property - it is only used by the client app.
    • Set the "org.sharedrecords.core.FileStoreRoot?" to something directory inside the space reserved for domain1 by the SJSAS - something like /opt/SUNWappserver/domains/domain1/applications/j2ee-modules/SRCStore/data_store will do.
    • Remember to create this directory if it does not exist.
  • Compile everything in /trunk/src/org/sharedrecords/core/ with the the "jaxrpc-*", "dom4j", "servlet" and "cos" jars on the classpath. Note that because we are not compiling the client application, we do not need any of the .jar files exclusively used by it. Put the .class files in build/. The ant task "build" in build.xml will do this step for you automatically.
  • Compile the webservice endpoint with wscompile. To do this, copy etc/config-interface.xml and etc/org.sharedrecords.properties to build/ and run

wscompile -define -mapping mapping.xml -d . -nd . -classpath . config-interface.xml

in the build/ directory. This step is done automatically by the ant "wscompile" task in build.xml

  • Create the .war file. Web archives are remarkably similar to .jar files in that they consist of a directory structure. Create a temporary directory called war/ .
    • Under war/WEB-INF/lib/ , place the "dom4j", "cos" and "jaxen" .jars.
    • Under war/WEB-INF/ , place the etc/sun-web.xml and etc/webservices.xml files.
    • Under war/WEB-INF/wsdl/ , place the newly-generated build/SRCDataStoreService.wsdl .
    • Under war/WEB-INF/build/ place the build/config-interface.xml and the newly-generated build/mapping.xml file, as well as *.class files, as they appear in the build/ directory.
    • Under war/ , place the etc/web.xml and etc/index.html files.
    • Under war/WEB-INF/classes/org/sharedrecords/core/utils , place the etc/org.sharedrecords.properties file.
    • You are now ready to package the web application.
    • Create a war file with war/web.xml as the webxml file, and include WEB-INF/*, build/*, org.sharedrecords.properties and index.html.

You will now have a file called SRCStore.war . The ant task "create-war" in build.xml will accomplish this step.

Creating the Web Archive File from Eclipse

In order to create the WAR file from within Eclipse, perform the configuration steps as noted above to specify the server specific properties such as the location of the data store and the Web Services configuration. In the Package explorer of Eclipse, navigate to build.xml. Right click on the Build in Place and select Run As -> Ant Build. This operation will copy away the .svn files and then copy them back into the appropriate location to avoid their inclusion into the WAR file. The War file will be created and placed in the root folder of your Eclipse project.

  • Note, if you recieve an error during the build task of ANT that states "com.sun.tools.javac.Main is not on the classpath. Perhaps JAVA_HOME does not point to the JDK", this is likely due to the fact that ANT is looking to run javac from your JRE installation instead of the JDK. This can be resolved by copying $JDK_INSTALL_DIRECTORY\lib\tools.jar to $JRE_INSTALL_DIRECTORY\lib\ext\tools.jar. The online resources we searched seem to have a variety of solutions that may or may not fix the issue (including overriding the windows registry to point to the JDK and re-ordering user environment variables). We have found this to be the easiest solution. If you do recieve an error during the build process, the restore-svn task of ANT may not run to copy the subversion files back into the correct folders. Run the restore-svn task to ensure the svn folders are properly copied back into the project correct folders.

Deploying from the WAR

To deploy the server from the WAR file, go to the server's administrative web interface at  http://localhost:4848(replacing localhost with the name of the server for remote server setup) go to 'Web Applications' and click on Deploy.