test

Sun Java System Access Manager 7 2005Q4 Developer's Guide

Chapter 12 Updating and Redeploying Access Manager WAR Files

Access Manager 7.0 2005Q4 contains a number of web application archive (WAR) files. These packages contain Java servlets and JavaServer PagesTM (JSP) pages you can modify to customize Access Manager to meet your needs. This chapter provides a general overview of WAR files, and describes the WAR files that come with Access Manager. The chapter contains the following sections:

WAR Files in J2EE Software Development

Access Manager is built upon the Java 2 Platform, Enterprise Edition (J2EE) platform which uses a component model to create full-scale applications. A component is self-contained functional software code assembled with other components into a J2EE application. The J2EE application components can be deployed separately on different servers. J2EE application components include the following:

Web Components

When a web browser executes a J2EE application, it deploys server-side objects known as web components. Java Server Pages (JSPs) and corresponding servlets are two such web components.

Servlets

Small Java programs that dynamically process requests and construct responses from a web browser. Servlets run within web containers.

Java Server Pages (JSPs)

Text-based documents that contain static template data such as HTML, Scalable Vector Graphics (SVG), Wireless Markup Language (WML), or eXtensible Markup Language (XML). JSPs also contain elements such as servlets that construct dynamic content.

How Web Components are Packaged

J2EE components are usually packaged separately, and then bundled together into an Enterprise Archive (EAR) file for application deployment. Web components are packaged in web application archives, also known as WAR files. Each WAR file contains servlets, JSPs, a deployment descriptor, and related resource files.

Static HTML files and JSP are stored at the top level of the WAR directory. The top-level directory contains the WEB-INF subdirectory which contains tag library descriptor files in addition to the following:

Server-side classes

Servlets, JavaBean components and related Java class files. These must be stored in the WEB-INF/classes directory.

Auxiliary JARs

Tag libraries and any utility libraries called by server-side classes. These must be stored in the WEB-INF/lib directory.

web.xml

The web component deployment descriptor is stored in the WEB-INF directory

About Access Manager WARs

When you customize Access Manager, you must modify the files included in Access Manager WARs, which results in changes to the web components. Remember that when you apply a patch or an upgrade to Access Manager, any customization you have implemented may be overwritten.

The Access Manager WARs are located in the following directory:

AccessManager-base/SUNWam and include:

console.war

The console.war contains files used by the Access Manager administration console.

Files You Can Modify

You can modify the following console.war files:

Files You Must Not Modify

Do not modify the following console.war files. Modifying these files may cause unintended Access Manager behaviors.

password.war

The password.war contains files used by the Access Manager password reset service.

Files You Can Modify

You can modify the following password.war files:

Files You Must Not Modify

Do not modify the following password.war files. Modifying the following files may cause unintended Access Manager behaviors.

services.war

The services.war contains files used by various Access Manager services.

Files You Can Modify

You can modify the following services.war files:

Files You Must Not Modify

Do not modify the following services.war files. Modifying the following files may cause Access Manager to fail:

Updating Modified WARs

Once a file within a WAR is modified, the WAR itself needs to be updated with the newly modified file. Following is the procedure to update a WAR.

ProcedureTo Update a Modified .war File

  1. cd AccessManager-base/ SUNWam

    This is the directory in which the WARs are kept.

  2. jar -uvf WARfilename.war < path_to_modified_file>

    The -uvf option replaces the old file with the newly modified file. For example:

    jar -uvf console.war newfile/index.html

    replaces the index.html file in console.war with the index.html file located in AccessManager-base/SUNWam/newfile .

  3. rm newfile/index.html

    Delete the modified file.

Redeploying Modified Access Manager WARs

Once updated, the WARs must be redeployed to their web container. The web container provides services such as request dispatching, security, concurrency, and life cycle management. The web container also gives the web components access to the J2EE APIs.

The BEA WebLogic Server 6.1 and Sun Java System Application Server web containers do not require WARs to be exploded. They are deployed as WARs. After redeploying the war files, you must restart all related servers.

ProcedureTo Redeploy a WAR On Sun Java System Web Server 6.1

  1. Delete the existing Access Manager web applications using the following form:

    server_root/bin/https/bin/wdeploy delete -u uri_path -i instance -v vs_id hard|softwhere the following variables are used:

    uri_path

    The URI prefix for the web application (requires a leading \x{201C}/\x{201D}).

    instance

    The server instance name.

    vs_id

    The virtual server ID.

    directory

    (Optional) The directory to which the application is deployed, or from which the application is deleted. If not specified for deployment, the application is deployed to instance_directory/webapps/vs_id/webappname. In this example, this directory is

    /opt/SUNWwbsvr/https-test/webapps/ https-test/testapp

    hard|soft

    Specifies whether both the directory and the server.xml entry are deleted (hard), or only the server.xml entry is deleted (soft).

    war_file

    The WAR file name.

    In the following example, the Sun Java System Web Server is installed in the directory /opt/SUNWwbsvr. To remove the amserver web application, use the following command: /opt/SUNWwbsvr/https/bin/wdeploy delete -u /amserver -i system.example.com -v https-system.example.com hard

    Repeat this step for all Access Manager applications such as /amserver , /amconsole , and /ampassword.

  2. Deploy the web application using the following form:

    wdeploy deploy -u uri_path -i instance -v vs_id [-d directory] war_file

    In this example, to deploy the amserver.war file, use the following command:

    /opt/SUNWwbsvr/https/bin/wdeploy deploy -u /amserver -i system.example.com -v https-system.example.com -d /opt/SUNWwbsvr/web-apps/services /opt/SUNWam/services.war

Sun Java System Web Server 6.1 SP4

For more information on deploying web applications, see the chapter “Deploying Web Applications,”http://docs.sun.com/source/817-6251/pwadeply.html#wp21505, in the Sun Java System Web Server 6.1 SP4 Programmer's Guide to Web Applications.

To Redeploy a WAR On BEA WebLogic Server 6.1

Run the Java command on the BEA WebLogic 6.1 Server using the following form:

java weblogic.deploy -url protocol://server_host:server_port
-component amconsole:WL61 _server_name 
deploy WL61_admin_password deployment_URI AccessManager-base/SUNWam/WARname.war

where the following variables are used:

protocol://server_host:server_port

The protocol [http | https] and fully-qualified name of the Access Manager server.

WL61 _server_name

The name of the WebLogic server.

WL61_admin_password

The WebLogic administrator password.

deployment_URI

For console.war, the deployment URI is amconsole.

For server.war, the deployment URI is amserver.

For password.war, the deployment UIR is ampassword.

AccessManager-base

The directory where the Access Manager server is installed.

WARname.war

The name of the WAR file to deploy.

[console.war | server.war | password.war]

For more complete information on the Java utility weblogic.deploy and its options, see the BEA WebLogic Server 6.1 documentation.

To Redeploy a WAR on Sun Java System Application Server 7.0

On the Application Server, run the asadmin command using the following form:

asadmin deploy -u S1AS_administrator 
-w  S1AS_administrator_password -H console_server_host
-p S1AS_server_port --type web secure_flag 
--contextroot deploy_uri --name deploy_uri 
--instance S1AS_instanceAccessManager-base/SUNWam/WARname

where the following variables are used:

S1AS_administrator

Application Server administrator

S1AS_administrator_password

Application Server administrator password

console_server_host

Access Manager server host name

S1AS_server_port

Application Server port number

deploy_uri

For console.war, the deployment URI is amconsole.

For password.war, the deployment URI is ampassword.

For service.war, the deployment URI is amservices.

S1AS_instance/AccessManager-base

Application Server directory where Access Manager server is installed

WARname.war

The name of the WAR file to deploy.

[console.war | server.war | password.war]

For more information on the asadmin deploy command and its options, see the Sun Java System Application Server 7.0 Developer’s Guide.

Redeploying an Access Manager WAR on IBM WebSphere Application Server

For detailed instructions on how to deploy WARs in an IBM WebSphere Application Server container, see the documentation that comes with the product: http://www-3.ibm.com/software/webservers/studio/doc/v40/studioguide/en/html/sdsscenario1.html.