test

Sun Java System Application Server Platform Edition 8.2 Developer's Guide

Part I Developing and Deploying Applications

Chapter 1 Setting Up a Development Environment

This chapter gives guidelines for setting up an application development environment in the Sun JavaTM System Application Server. Setting up an environment for creating, assembling, deploying, and debugging your code involves installing the mainstream version of the Application Server and making use of development tools. In addition, sample applications are available. These topics are covered in the following sections:

Installing and Preparing the Server for Development

For the Sun Java Enterprise System, Application Server installation is part of the system installation process. For more information, see http://www.sun.com/software/javaenterprisesystem/index.html.

For all other installations, the following components are included in the full installation. For more information, see the Sun Java System Application Server Platform Edition 8.2 Installation Guide.

The NetBeans IDE bundles the Platform Edition of the Application Server, so information about this IDE is provided as well.

After you have installed Application Server, you can further optimize the server for development in these ways:

Tools

The following general tools are provided with the Application Server:

The following development tools are provided with the Application Server or downloadable from Sun:

The following third-party tools might also be useful:

The asadmin Command

The asadmin command allows you to configure a local or remote server and perform both administrative and development tasks at the command line. For general information about asadmin, see the Sun Java System Application Server Platform Edition 8.2 Reference Manual.

The asadmin command is located in the install-dir/bin directory. Type asadmin help for a list of subcommands.

The Administration Console

The Administration Console lets you configure the server and perform both administrative and development tasks using a web browser. For general information about the Administration Console, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

To access the Administration Console, type http://host:4848 in your browser. The host is the name of the machine on which the Application Server is running.

NetBeans IDE

The NetBeansTM IDE (integrated development environment) allows you to create, assemble, and debug code from a single, easy-to-use interface. The Platform Edition of the Application Server is bundled with the NetBeans 5 IDE. For more information about using the NetBeans IDE, see http://www.netbeans.org.

The asant Utility

Apache Ant 1.6.5 is provided with the Application Server and can be launched from the bin directory using the command asant. The Application Server also provides server-specific tasks for deployment; see asant Assembly and Deployment Tool. The sample applications provided with the Application Server use Ant build.xml files; see Sample Applications.

For more information about Ant, see the Apache Software Foundation web site at http://ant.apache.org/.

deploytool

You can use the deploytool, provided with Application Server, to assemble J2EE applications and modules, configure deployment parameters, perform simple static checks, and deploy the final result. For more information about using the deploytool, see the J2EE 1.4 Tutorial at http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html.

Verifier

The verifier tool checks a J2EE application file (EAR, JAR, WAR, RAR), including Java classes and deployment descriptors, for compliance with J2EE specifications. Use it to check whether an application has obvious bugs and to make applications portable across application servers. The verifier can be launched from the deploytool or from the command line. For more information, see The Deployment Descriptor Verifier.

Migration Tool

The Migration Tool reassembles J2EE applications and modules developed on other application servers. For more information and to download the Migration Tool, see http://java.sun.com/j2ee/tools/migration/index.html.

For additional information on migration, see the Sun Java System Application Server Platform Edition 8.2 Upgrade and Migration Guide.

Debugging Tools

You can use several debuggers with the Application Server. For more information, see Chapter 4, Debugging Applications.

Profiling Tools

You can use several profilers with the Application Server. For more information, see Profiling.

Sample Applications

Sample applications that you can examine and deploy are included with the full installation of the Application Server. You can also download these samples separately if you installed the Application Server without them initially.

If installed with the Application Server, the samples are in the install-dir/samples directory. The samples are organized in categories such as ejb, jdbc, connectors, i18n, and so on. Each sample category is further divided into subcategories. For example, under the ejb category are stateless, stateful, security, mdb, bmp, and cmp subcategories.

Most Application Server samples have the following directory structure:

With a few exceptions, sample applications follow the standard directory structure described here: http://java.sun.com/blueprints/code/projectconventions.html.

The install-dir/samples/common-ant.xml file defines properties common to all sample applications and implements targets needed to compile, assemble, deploy and undeploy sample applications. In most sample applications, the build.xml file includes common-ant.xml.

For a detailed description of the helloworld sample and how to deploy and run it, see the associated documentation at:

install-dir/samples/ejb/stateless/apps/simple/docs/index.html

After you deploy the helloworld sample in Application Server, you can invoke it using the following URL:

http://server:port/helloworld

Chapter 2 Securing Applications

This chapter describes how to write secure J2EE applications, which contain components that perform user authentication and access authorization for servlets and EJB business logic. For information about administrative security for the server, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

This chapter contains the following sections:

Security Goals

In an enterprise computing environment, there are many security risks. The goal of the Sun Java System Application Server is to provide highly secure, interoperable, and distributed component computing based on the J2EE security model. Security goals include:

Application Server Specific Security Features

The Application Server supports the J2EE v1.4 security model, as well as the following features which are specific to the Application Server:

Container Security

The component containers are responsible for providing J2EE application security. There are two security forms provided by the container:

Programmatic Security

Programmatic security is when an EJB component or servlet uses method calls to the security API, as specified by the J2EE security model, to make business logic decisions based on the caller or remote user’s security role. Programmatic security should only be used when declarative security alone is insufficient to meet the application’s security model.

The J2EE specification, v1.4 defines programmatic security as consisting of two methods of the EJB EJBContext interface and two methods of the servlet HttpServletRequest interface. The Application Server supports these interfaces as specified in the specification.

For more information on programmatic security, see the following:

Declarative Security

Declarative security means that the security mechanism for an application is declared and handled externally to the application. Deployment descriptors describe the J2EE application’s security structure, including security roles, access control, and authentication requirements.

The Application Server supports the deployment descriptors specified by J2EE v1.4 and has additional security elements included in its own deployment descriptors. Declarative security is the application deployer’s responsibility.

There are two levels of declarative security, as follows:

Application Level Security

The application XML deployment descriptor (application.xml) contains descriptors for all user roles for accessing the application’s servlets and EJB components. On the application level, all roles used by any application container must be listed in a role-name element in this file. The role names are scoped to the EJB XML deployment descriptors (ejb-jar.xml and sun-ejb-jar.xml files) and to the servlet XML deployment descriptors (web.xml and sun-web.xml files). The sun-application.xml file must also contain matching security-role-mapping elements for each role-name used by the application.

Component Level Security

Component level security encompasses web components and EJB components.

A secure web container authenticates users and authorizes access to a servlet or JSP by using the security policy laid out in the servlet XML deployment descriptors (web.xml and sun-web.xml files).

The EJB container is responsible for authorizing access to a bean method by using the security policy laid out in the EJB XML deployment descriptors (ejb-jar.xml and sun-ejb-jar.xml files).

Realm Configuration

This section covers the following topics:

Supported Realms

The following realms are supported in the Application Server:

For detailed information about configuring each of these realms, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

How to Configure a Realm

You can configure a realm in one of these ways:

How to Set a Realm for an Application or Module

The following deployment descriptor elements have optional realm or realm-name data subelements or attributes that override the domain’s default realm:

If modules within an application specify realms, these are ignored. If present, the realm defined in sun-application.xml is used, otherwise the domain’s default realm is used.

For example, a realm is specified in sun-application.xml as follows:

<sun-application>
    ...
    <realm>ldap</realm>
</sun-application>

For more information about the deployment descriptor files and elements, see Appendix A, Deployment Descriptor Files.

Creating a Custom Realm

You can create a custom realm by providing a custom Java Authentication and Authorization Service (JAAS) login module class and a custom realm class. Note that client-side JAAS login modules are not suitable for use with the Application Server.

JAAS is a set of APIs that enable services to authenticate and enforce access controls upon users. JAAS provides a pluggable and extensible framework for programmatic user authentication and authorization. JAAS is a core API and is an underlying technology for Java EE security mechanisms. For more information about JAAS, refer to the JAAS specification for Java SDK, available at http://java.sun.com/products/jaas/.

For general information about realms and login modules, see the Security chapter of the J2EE 1.4 Tutorial.

Custom login modules must extend the com.sun.appserv.security.AppservPasswordLoginModule class. This class implements javax.security.auth.spi.LoginModule. Custom login modules must not implement LoginModule directly.

Custom login modules must provide an implementation for one abstract method defined in AppservPasswordLoginModule:

abstract protected void authenticateUser() throws LoginException

This method performs the actual authentication. The custom login module must not implement any of the other methods, such as login(), logout(), abort(), commit(), or initialize(). Default implementations are provided in AppservPasswordLoginModule which hook into the Application Server infrastructure.

The custom login module can access the following protected object fields, which it inherits from AppservPasswordLoginModule. These contain the user name and password of the user to be authenticated:

protected String _username;
protected String _password;

The authenticateUser() method must end with the following sequence:

String[] grpList;
// populate grpList with the set of groups to which
// _username belongs in this realm, if any
return commitUserAuthentication(_username, _password, 
  _currentRealm, grpList);

Custom realms must extend the com.sun.appserv.security.AppservRealm class and implement the following methods:

public void init(Properties props) throws BadRealmException, 
NoSuchRealmException

This method is invoked during server startup when the realm is initially loaded. The props argument contains the properties defined for this realm in domain.xml. The realm can do any initialization it needs in this method. If the method returns without throwing an exception, the Application Server assumes the realm is ready to service authentication requests. If an exception is thrown, the realm is disabled.

public String getAuthType()

This method returns a descriptive string representing the type of authentication done by this realm.

public abstract Enumeration getGroupNames(String username) throws 
InvalidOperationException, NoSuchUserException

This method returns an Enumeration (of String objects) enumerating the groups (if any) to which the given username belongs in this realm.

JACC Support

JACC (Java Authorization Contract for Containers) is part of the J2EE 1.4 specification and defined by JSR-115. JACC defines an interface for pluggable authorization providers. This provides third parties with a mechanism to develop and plug in modules that are responsible for answering authorization decisions during J2EE application execution. The interfaces and rules used for developing JACC providers are defined in the JACC 1.0 specification.

The Application Server provides a simple file-based JACC-compliant authorization engine as a default JACC provider. To configure an alternate provider using the Administration Console, open the Security component under the relevant configuration, and select the JACC Providers component. For details, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

Pluggable Audit Module Support

You can create a custom audit module. This section covers the following topics:

Configuring an Audit Module

To configure an audit module, you can perform one of the following tasks:

The AuditModule Class

You can create a custom audit module by implementing a class that extends com.sun.appserv.security.AuditModule. The AuditModule class provides default “no-op” implementations for each of the following methods, which your custom class can override.

public void init(Properties props)

This method is invoked during server startup when the audit module is initially loaded. The props argument contains the properties defined for this module in domain.xml. The module can do any initialization it needs in this method. If the method returns without throwing an exception, the Application Server assumes the module realm is ready to service audit requests. If an exception is thrown the module is disabled.

public void authentication(String user, String realm, boolean success)

This method is invoked when an authentication request has been processed by a realm for the given user. The success flag indicates whether the authorization was granted or denied.

public void webInvocation(String user, HttpServletRequest req, String type, 
boolean success)

This method is invoked when a web container call has been processed by authorization. The success flag indicates whether the authorization was granted or denied. The req object is the standard HttpServletRequest object for this request. The type string is one of hasUserDataPermission or hasResourcePermission (see JSR-115).

public void ejbInvocation(String user, String ejb, String method, boolean 
success)

This method is invoked when an EJB container call has been processed by authorization. The success flag indicates whether the authorization was granted or denied. The ejb and method strings describe the EJB component and its method that is being invoked.

The server.policy File

Each Application Server domain has its own standard J2SE policy file, located in domain-dir/config. The file is named server.policy.

The Application Server is a J2EE 1.4 compliant application server. As such, it follows the requirements of the J2EE specification, including the presence of the security manager (the Java component that enforces the policy) and a limited permission set for J2EE application code.

This section covers the following topics:

Default Permissions

Internal server code is granted all permissions. These are covered by the AllPermission grant blocks to various parts of the server infrastructure code. Do not modify these entries.

Application permissions are granted in the default grant block. These permissions apply to all code not part of the internal server code listed previously. The Application Server does not distinguish between EJB and web module permissions. All code is granted the minimal set of web component permissions (which is a superset of the EJB minimal set).

A few permissions above the minimal set are also granted in the default server.policy file. These are necessary due to various internal dependencies of the server implementation. J2EE application developers must not rely on these additional permissions.

One additional permission is granted specifically for using connectors. If connectors are not used in a particular domain, you should remove this permission, because it is not otherwise necessary.

Changing Permissions for an Application

The default policy for each domain limits the permissions of J2EE deployed applications to the minimal set of permissions required for these applications to operate correctly. Do not add extra permissions to the default set (the grant block with no codebase, which applies to all code). Instead, add a new grant block with a codebase specific to the applications requiring the extra permissions, and only add the minimally necessary permissions in that block.

If you develop multiple applications that require more than this default set of permissions, you can add the custom permissions that your applications need. The com.sun.aas.instanceRoot variable refers to the domain-dir. For example:

grant "file:${com.sun.aas.instanceRoot}/applications/j2ee-apps/-" { ... }

You can add permissions to stub code with the following grant block:

grant "file:${com.sun.aas.instanceRoot}/generated/-" { ... }

In general, you should add extra permissions only to the applications or modules that require them, not to all applications deployed to a domain. For example:

grant "file:${com.sun.aas.instanceRoot}/applications/j2ee-apps/MyApp/-" { ... }

For a module:

grant "file:${com.sun.aas.instanceRoot}/applications/j2ee-modules/MyModule/-" { ... }

Do not add extra permissions to the default set (the grant block with no codebase, which applies to all code). Instead, add a new grant block with a codebase specific to the application requiring the extra permissions, and only add the minimally necessary permissions in that block.

Note –

Do not add java.security.AllPermission to the server.policy file for application code. Doing so completely defeats the purpose of the security manager, yet you still get the performance overhead associated with it.

As noted in the J2EE specification, an application should provide documentation of the additional permissions it needs. If an application requires extra permissions but does not document the set it needs, contact the application author for details.

As a last resort, you can iteratively determine the permission set an application needs by observing AccessControlException occurrences in the server log. If this is not sufficient, you can add the -Djava.security.debug=fail JVM option to the domain. For details, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide or the Sun Java System Application Server Platform Edition 8.2 Administration Reference.

You can use the J2SE standard policytool or any text editor to edit the server.policy file. For more information, see:

http://java.sun.com/docs/books/tutorial/security1.2/tour2/index.html

For detailed information about the permissions you can set in the server.policy file, see:

http://java.sun.com/j2se/1.4/docs/guide/security/permissions.html

The Javadoc for the Permission class is at:

http://java.sun.com/j2se/1.4/docs/api/java/security/Permission.html

Configuring Message Security

In message security, security information travels along with the web services message. WSS in the SOAP layer is the use of XML Encryption and XML Digital Signatures to secure SOAP messages. WSS profiles the use of various security tokens including X.509 certificates, SAML assertions, and username/password tokens to achieve this.

Message layer security differs from transport layer security (which is discussed in the Security chapter of the J2EE 1.4 Tutorial) in that message layer security can be used to decouple message protection from message transport so that messages remain protected after transmission, regardless of how many hops they travel on.

WSS is a security mechanism that is applied at the message-layer in order to secure web services. For the purposes of this document, when we discuss WSS, we are talking about security for web services as described by the Oasis Web Services Security (WSS) specification. Message security for the Application Server follows this specification, which can be viewed at the following URL:

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

For more information about message security, see the following:

The following web services security topics are discussed in this section:

Message Security Responsibilities

Message security responsibilities are assigned to the following:

Application Developer

The application developer can implement message security, but is not responsible for doing so. Message security can be set up by the System Administrator so that all web services are secured, or set up by the Application Deployer when the Application Server provider configuration is insufficient.

The application developer is responsible for the following:

Application Deployer

The application deployer is responsible for:

These security tasks are discussed in Application-Specific Message Protection. An example application using message security is discussed in Understanding and Running the Example Application.

System Administrator

The system administrator is responsible for:

A system administrator uses the Admin Console or the asadmin tool to manage server security settings and keytool to manage certificates. System administrator tasks are discussed in the Configuring Message Security chapter of the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

Application-Specific Message Protection

When the Application Server provided configuration is insufficient for your security needs, and you want to override the default protection, you can apply application-specific message security to a web service.

Application-specific security is implemented by adding the message security binding to the web service endpoint, whether it is an EJB or servlet web service endpoint. Modify Sun-specific XML files to add the message binding information.

For more details on message security binding for EJB web services, servlet web services, and clients, see the XML file descriptions in Appendix A, Deployment Descriptor Files.

This section contains the following topics:

Using a Signature to Enable Message Protection for All Methods

To enable message protection for all methods using digital signature, update the message-security-binding element for the EJB web service endpoint in the application’s sun-ejb-jar.xml file. In this file, add request-protection and response-protection elements, which are analogous to the request-policy and response-policy elements discussed in the Configuring Message Security chapter of the Sun Java System Application Server Platform Edition 8.2 Administration Guide. In order to apply the same protection mechanisms for all methods, leave the method-name element blank. Configuring Message Protection For a Specific Method Based on Digital Signatures discusses listing specific methods or using wildcard characters.

This section uses the sample application discussed in Understanding and Running the Example Application to apply application-level message security in order to show only the differences necessary for protecting web services using various mechanisms.

ProcedureTo enable message protection for all methods using digital signature

  1. In a text editor, open the application’s sun-ejb-jar.xml file.

    For the xms example, this file is located in the directory install-dir /samples/webservices/security/ejb/apps/xms/xms-ejb/src/conf.

  2. Modify the sun-ejb-jar.xml file by adding the message-security-binding element as shown:

    <sun-ejb-jar>
  <enterprise-beans>
    <unique-id>1</unique-id>
    <ejb>
      <ejb-name>HelloWorld</ejb-name>
      <jndi-name>HelloWorld</jndi-name>
      <webservice-endpoint>
        <port-component-name>HelloIF</port-component-name>
        <endpoint-address-uri>service/HelloWorld</endpoint-address-uri>
        <message-security-binding auth-layer="SOAP">
          <message-security>
            <request-protection auth-source="content" />
            <response-protection auth-source="content"/>
          </message-security>
        </message-security-binding>
      </webservice-endpoint>
    </ejb>
  </enterprise-beans>
</sun-ejb-jar>

  3. Compile, deploy, and run the application as described in To Run the Sample Application.

Configuring Message Protection For a Specific Method Based on Digital Signatures

To enable message protection for a specific method, or for a set of methods that can be identified using a wildcard value, follow these steps. As in the example discussed in Using a Signature to Enable Message Protection for All Methods, to enable message protection for a specific method, update the message-security-binding element for the EJB web service endpoint in the application’s sun-ejb-jar.xml file. To this file, add request-protection and response-protection elements, which are analogous to the request-policy and response-policy elements discussed in the Configuring Message Security chapter of the Sun Java System Application Server Platform Edition 8.2 Administration Guide. The Administration Guide includes a table listing the set and order of security operations for different request and response policy configurations.

This section uses the sample application discussed in Understanding and Running the Example Application to apply application-level message security in order to show only the differences necessary for protecting web services using various mechanisms.

ProcedureTo enable message protection for a particular method or set of methods using digital signature

  1. In a text editor, open the application’s sun-ejb-jar.xml file.

    For the xms example, this file is located in the directory install-dir/samples/webservices/security/ejb/apps/xms/xms-ejb/src/conf.

  2. Modify the sun-ejb-jar.xml file by adding the message-security-binding element as shown:

    <sun-ejb-jar>
  <enterprise-beans>
  <unique-id>1</unique-id>
    <ejb>
      <ejb-name>HelloWorld</ejb-name>
      <jndi-name>HelloWorld</jndi-name>
      <webservice-endpoint>
        <port-component-name>HelloIF</port-component-name>
        <endpoint-address-uri>service/HelloWorld</endpoint-address-uri>
        <message-security-binding auth-layer="SOAP">
          <message-security>
            <message>
              <java-method>
                <method-name>ejbCreate</method-name>
              </java-method>
            </message>
            <message>
              <java-method>
                <method-name>sayHello</method-name>
              </java-method>
            </message>
            <request-protection auth-source="content" />
            <response-protection auth-source="content"/>
          </message-security>
        </message-security-binding>
      </webservice-endpoint>
    </ejb>
  </enterprise-beans>
</sun-ejb-jar>

  3. Compile, deploy, and run the application as described in To Run the Sample Application.

Understanding and Running the Example Application

This section discusses the WSS sample application, xms, which is located in the directory install-dir/samples/webservices/security/ejb/apps/xms/. This directory and this sample application is installed on your system only if you have selected to install the samples server when you installed the Application Server. If you have not installed the samples, see To Set Up the Sample Application.

The objective of this sample application is to demonstrate how a web service can be secured with WSS. The web service in the xms example is a simple web service implemented using a J2EE EJB endpoint and a web service endpoint implemented using a servlet. In this example, a service endpoint interface is defined with one operation, sayHello, which takes a string then sends a response with Hello prefixed to the given string. You can view the WSDL file for the service endpoint interface at install-dir/samples/webservices/security/ejb/apps/xms/xms-ejb/src/conf/HelloWorld.wsdl.

In this application, the client lookups the service using the JNDI name java:comp/env/service/HelloWorld and gets the port information using a static stub to invoke the operation using a given name. For the name Duke, the client gets the response Hello Duke!

This example shows how to use message security for web services at the Application Server level and at the application level. The WSS message security mechanisms implement message-level authentication (for example, XML digital signature and encryption) of SOAP web services invocations using the X.509 and username/password profiles of the OASIS WS-Security standard, which can be viewed from the following URL:

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

This section includes the following topics:

ProcedureTo Set Up the Sample Application

Before You Begin

The example application is located in the directory install-dir/samples/webservices/security/ejb/apps/xms/. For ease of reference throughout the rest of this section, this directory is referred to as simply app-dir/xms/.

In order to have access to this sample application, you must have installed the samples server during installation of the Application Server. To check to see if the samples are installed, browse to the directory install-dir/samples/webservices/security/ejb/apps/xms/. If this directory exists, you do not need to follow the steps in the following section. If this directory does not exist, the samples server is not installed, and must be installed for access to the sample application discussed here.

  1. Start the installation for the Application Server.

  2. Click Next on the Welcome page.

  3. Click Yes on the Software License Agreement page. Click Next.

  4. Click Next to accept the installation directory, or change it to match the location where the Application Server is currently installed.

  5. Select Continue to install to the same directory.

    You want to do this because you want the samples/ directory to be a subdirectory of the Application Server directory, install-dir/samples/.

  6. Reenter the Admin User Name and Password. Click Next.

    You are on the page where you select to install just the samples.

  7. Deselect everything except Create Samples Server. Click Next.

  8. Click Install Now to install the samples.

  9. Click Finish to complete the installation.

ProcedureTo Run the Sample Application

  1. Make sure that the Application Server is running.

    Message security providers are set up when the asant targets are run, so you don’t need to configure these on the Application Server prior to running this example.

  2. If you are not running HTTP on the default port of 8080, change the WSDL file for the example to reflect the change, and change the common.properties file to reflect the change as well.

    The WSDL file for this example is located at install-dir/samples/webservices/security/ejb/apps/xms/xms-ejb/src/conf/HelloWorld.wsdl. The port number is in the following section:

    <service name="HelloWorld">
  <port name="HelloIFPort" binding="tns:HelloIFBinding">
    <soap:address location="http://localhost:8080/service/HelloWorld"/>
  </port>
</service>

    Verify that the properties in the install-dir/samples/common.properties file are set properly for your installation and environment. If you need more description of this file, refer to the Configuration section for the web services security applications at install-dir/samples/webservices/security/docs/common.html#Logging.

  3. Change to the install-dir/samples/webservices/security/ejb/apps/xms/ directory.

  4. Run the following asant targets to compile, deploy, and run the example application:

    1. To compile samples:

      asant

    2. To deploy samples:

      asant deploy

    3. To run samples:

      asant run

    If the sample has compiled and deployed properly, you see the following response on your screen after the application has run:

    run:[echo] Running the xms program:[exec] Established message level security : Hello Duke!

  5. To undeploy the sample, run the following asant target:


    asant undeploy

    All of the web services security examples use the same web service name (HelloWorld) and web service ports in order to show only the differences necessary for protecting web services using various mechanisms. Make sure to undeploy an application when you have completed running it, or you receive an Already in Use error and deployment failures when you try to deploy another web services example application.

Programmatic Login

Programmatic login allows a deployed J2EE application to invoke a login method. If the login is successful, a SecurityContext is established as if the client had authenticated using any of the conventional J2EE mechanisms.

Programmatic login is useful for an application having special needs that cannot be accommodated by any of the J2EE standard authentication mechanisms.

Note –

Programmatic login is specific to the Application Server and not portable to other application servers.

This section contains the following topics:

Precautions

The Application Server is not involved in how the login information (user, password) is obtained by the deployed application. Programmatic login places the burden on the application developer with respect to assuring that the resulting system meets their security requirements. If the application code reads the authentication information across the network, it is up to the application to determine whether to trust the user.

Programmatic login allows the application developer to bypass the application server-supported authentication mechanisms and feed authentication data directly to the security service. While flexible, this capability should not be used without some understanding of security issues.

Since this mechanism bypasses the container-managed authentication process and sequence, the application developer must be very careful in making sure that authentication is established before accessing any restricted resources or methods. It is also the application developer’s responsibility to verify the status of the login attempt and to alter the behavior of the application accordingly.

The programmatic login state does not necessarily persist in sessions or participate in single sign-on.

Lazy authentication is not supported for programmatic login. If an access check is reached and the deployed application has not properly authenticated via the programmatic login method, access is denied immediately and the application might fail if not properly coded to account for this occurrence.

Granting Programmatic Login Permission

The ProgrammaticLoginPermission permission is required to invoke the programmatic login mechanism for an application. This permission is not granted by default to deployed applications because this is not a standard J2EE mechanism.

To grant the required permission to the application, add the following to the domain-dir/config/server.policy file:

grant codeBase "file:jar-file-path" {
     permission com.sun.appserv.security.ProgrammaticLoginPermission
     "login";
 };

The jar-file-path is the path to the application’s JAR file.

For more information about the server.policy file, see The server.policy File

The ProgrammaticLogin Class

The com.sun.appserv.security.ProgrammaticLogin class enables a user to perform login programmatically. This class has four login methods, two for servlets or JSP files and two for EJB components.

The login methods for servlets or JSP files have the following signatures:

public java.lang.Boolean login(String user, String password, 
    javax.servlet.http.HttpServletRequest request, 
    javax.servlet.http.HttpServletResponse response)
public java.lang.Boolean login(String user, String password, 
    String realm, javax.servlet.http.HttpServletRequest request, 
    javax.servlet.http.HttpServletResponse response, boolean errors) 
    throws java.lang.Exception

The login methods for EJB components have the following signatures:

public java.lang.Boolean login(String user, String password)
public java.lang.Boolean login(String user, String password, 
    String realm, boolean errors) throws java.lang.Exception

All of these login methods:

The login occurs on the realm specified unless it is null, in which case the domain’s default realm is used. The methods with no realm parameter use the domain’s default realm.

If the errors flag is set to true, any exceptions encountered during the login are propagated to the caller. If set to false, exceptions are thrown.

On the client side, realm and errors parameters are ignored and the actual login does not occur until a resource requiring a login is accessed. A java.rmi.AccessException with COBRA NO_PERMISSION occurs if the actual login fails.

The logout methods for servlets or JSP files have the following signatures:

public java.lang.Boolean logout(HttpServletRequest request, 
    HttpServletResponse response)
public java.lang.Boolean logout(HttpServletRequest request, 
    HttpServletResponse response, boolean errors) 
    throws java.lang.Exception

The logout methods for EJB components have the following signatures:

public java.lang.Boolean logout()
public java.lang.Boolean logout(boolean errors) 
    throws java.lang.Exception

All of these logout methods return true if logout succeeded, false if logout failed.

If the errors flag is set to true, any exceptions encountered during the logout are propagated to the caller. If set to false, exceptions are thrown.

User Authentication for Single Sign-on

The single sign-on feature of the Application Server allows multiple web applications deployed to the same virtual server to share the user authentication state. With single sign-on enabled, users who log in to one web application become implicitly logged into other web applications on the same virtual server that require the same authentication information. Otherwise, users would have to log in separately to each web application whose protected resources they tried to access.

An example application using the single sign-on scenario could be a consolidated airline booking service that searches all airlines and provides links to different airline web sites. Once the user signs on to the consolidated booking service, the user information can be used by each individual airline site without requiring another sign-on.

Single sign-on operates according to the following rules:

The single sign-on feature utilizes HTTP cookies to transmit a token that associates each request with the saved user identity, so it can only be used in client environments that support cookies.

To configure single sign-on, set the following properties in the virtual-server element of the domain.xml file:

Here is an example configuration with all default values:

<virtual-server id="server" ... >
     ...
    <property name="sso-enabled" value="true"/>
     <property name="sso-max-inactive-seconds" value="450"/>
     <property name="sso-reap-interval-seconds" value="80"/>
 </virtual-server>

Defining Roles

You define roles in the J2EE deployment descriptor file, web.xml, and the corresponding role mappings in the Application Server deployment descriptor file, sun-application.xml (or sun-web.xml for individually deployed web modules).

For more information regarding web.xml elements, see Chapter 13, “Deployment Descriptor,” of the Java Servlet Specification, v2.4. For more information regarding sun-web.xml and sun-application.xml elements, see Appendix A, Deployment Descriptor Files.

Each security-role-mapping element in the sun-application.xml or sun-web.xml file maps a role name permitted by the web application to principals and groups. For example, a sun-web.xml file for an individually deployed web module might contain the following:

<sun-web-app>
    <security-role-mapping>
        <role-name>manager</role-name>
        <principal-name>jgarcia</principal-name>
        <principal-name>mwebster</principal-name>
        <group-name>team-leads</group-name>
    </security-role-mapping>
    <security-role-mapping>
        <role-name>administrator</role-name>
        <principal-name>dsmith</principal-name>
    </security-role-mapping>
</sun-web-app>

Note that the role-name in this example must match the role-name in the security-role element of the corresponding web.xml file.

Note that for J2EE applications (EAR files), all security role mappings for the application modules must be specified in the sun-application.xml file. For individually deployed web modules, the roles are always specified in the sun-web.xml file. A role can be mapped to either specific principals or to groups (or both). The principal or group names used must be valid principals or groups in the current default realm.

Chapter 3 Assembling and Deploying Applications

This chapter describes Sun Java System Application Server modules and how these modules are assembled separately or together in an application. This chapter also describes classloaders and tools for assembly and deployment.

The Application Server modules and applications include J2EE standard features and Application Server specific features. Only Application Server specific features are described in detail in this chapter.

The following topics are presented in this chapter:

Overview of Assembly and Deployment

Application assembly (also known as packaging) is the process of combining discrete components of an application into a single unit that can be deployed to a J2EE-compliant application server. A package can be classified either as a module or as a full-fledged application. This section covers the following topics:

Modules

A J2EE module is a collection of one or more J2EE components of the same container type (for example, web or EJB) with deployment descriptors of that type. One descriptor is J2EE standard, the other is Application Server specific. Types of J2EE modules are as follows:

Package definitions must be used in the source code of all modules so the class loader can properly locate the classes after the modules have been deployed.

Because the information in a deployment descriptor is declarative, it can be changed without requiring modifications to source code. At run time, the J2EE server reads this information and acts accordingly.

The Application Server also supports lifecycle modules. See Chapter 10, Developing Lifecycle Listeners for more information.

EJB JAR and Web modules can also be deployed separately, outside of any application, as in the following figure. EJB components are assembled in a JAR file with ejb-jar.xml and sun-ejb-jar.xml deployment descriptors. Web components are assembled in a WAR file with web.xml and sun-web.xml deployment descriptors. Both module types are deployed to the Application Server.

Figure 3–1 Module assembly and deployment

Figure shows EJB or Web module assembly and deployment.

Applications

A J2EE application is a logical collection of one or more J2EE modules tied together by application deployment descriptors. Components can be assembled at either the module or the application level. Components can also be deployed at either the module or the application level.

The following diagram illustrates how components are assembled into modules and then assembled into an Application Server application and deployed. EJB components are assembled in a JAR file with ejb-jar.xml and sun-ejb-jar.xml deployment descriptors. Web components are assembled in a WAR file with web.xml and sun-web.xml deployment descriptors. An application client is assembled in a JAR file with application-client.xml and sun-application-client.xml deployment descriptors. A resource adapter is assembled in a RAR file with a ra.xml deployment descriptor. All modules are assembled in an EAR file and deployed to the Application Server.

Figure 3–2 Application assembly and deployment

Figure shows J2EE application assembly and deployment.

Each module has an Application Server deployment descriptor and a J2EE deployment descriptor. The Application Server uses the deployment descriptors to deploy the application components and to register the resources with the Application Server.

An application consists of one or more modules, an optional Application Server deployment descriptor, and a required J2EE application deployment descriptor. All items are assembled, using the Java ARchive (.jar) file format, into one file with an extension of .ear.

J2EE Standard Descriptors

The J2EE platform provides assembly and deployment facilities. These facilities use WAR, JAR, and EAR files as standard packages for components and applications, and XML-based deployment descriptors for customizing parameters.

J2EE standard deployment descriptors are described in the J2EE specification, v1.4. You can find the specification at http://java.sun.com/products/.

To check the correctness of these deployment descriptors prior to deployment, see The Deployment Descriptor Verifier.

The following table shows where to find more information about J2EE standard deployment descriptors.

Table 3–1 J2EE Standard Descriptors

Deployment Descriptor  

Where to Find More Information  

application.xml

Java 2 Platform Enterprise Edition Specification, v1.4, Chapter 8, “Application Assembly and Deployment - J2EE:application XML DTD” 

web.xml

Java Servlet Specification, v2.4 Chapter 13, “Deployment Descriptor,” and JavaServer Pages Specification, v2.0, Chapter 7, “JSP Pages as XML Documents,” and Chapter 5, “Tag Extensions” 

ejb-jar.xml

Enterprise JavaBeans Specification, v2.1, Chapter 16, “Deployment Descriptor” 

application-client.xml

Java 2 Platform Enterprise Edition Specification, v1.4, Chapter 9, “Application Clients - J2EE:application-client XML DTD” 

ra.xml

Java 2 Enterprise Edition, J2EE Connector Architecture Specification, v1.0, Chapter 10, “Packaging and Deployment.” 

Sun Java System Application Server Descriptors

The Application Server uses additional deployment descriptors for configuring features specific to the Application Server. The sun-application.xml, sun-web.xml, and sun-cmp-mappings.xml files are optional; all the others are required.

To check the correctness of these deployment descriptors prior to deployment, see The Deployment Descriptor Verifier.

The following table lists the Application Server deployment descriptors and their DTD files. For complete descriptions of these files, see Appendix A, Deployment Descriptor Files.

Table 3–2 Sun Java System Application Server Descriptors

Deployment Descriptor  

DTD File  

Description  

sun-application.xml

sun-application_1_4-0.dtd

Configures an entire J2EE application (EAR file). 

sun-web.xml

sun-web-app_2_4-1.dtd

Configures a web application (WAR file). 

sun-ejb-jar.xml

sun-ejb-jar_2_1-1.dtd

Configures an enterprise bean (EJB JAR file). 

sun-cmp-mappings.xml

sun-cmp-mapping_1_2.dtd

Configures container-managed persistence for an enterprise bean. 

sun-application-client.xml

sun-application-client_1_4-1.dtd

Configures an Application Client Container (ACC) client (JAR file). 

sun-acc.xml

sun-application-client-container_1_0.dtd

Configures the Application Client Container. 

Naming Standards

Names of applications and individually deployed EJB JAR, WAR, and connector RAR modules must be unique within an Application Server domain. Modules of the same type within an application must have unique names. In addition, for entity beans that use CMP,.dbschema file names must be unique within an application.

If you do not explicitly specify a name, the default name is the first portion of the file name (without the .war or .jar extension). Modules of different types can have the same name within an application, because the directories holding the individual modules are named with _jar, _war and _rar suffixes. This is the case when you use the Administration Console, the asadmin command, or the deploytool to deploy an application or module. See Tools for Deployment.

Make sure your package and file names do not contain spaces or characters that are illegal for your operating system.

If you are writing your own JSR 88 client to deploy applications to the Application Server using the following API, the name of the application is taken from the display-name entry in the J2EE standard deployment descriptor, because there is no file name in this case. If the display-name entry is not present, the Application Server creates a temporary file name and uses that name to deploy the application.

javax.enterprise.deploy.spi.DeploymentManager.distribute(Target[], 
InputStream, InputStream)

Neither the Administration Console, the asadmin command, nor the deploytool uses this API.

For more information about JSR 88, see the JSR 88 page at http://jcp.org/en/jsr/detail?id=88.

Directory Structure

When you deploy an application, the application is expanded to an open directory structure, and the directories holding the individual modules are named with _jar, _war and _rar suffixes. If you use the asadmin deploydir command to deploy a directory instead of an EAR file, your directory structure must follow this same convention.

Module and application directory structures follow the structure outlined in the J2EE specification. Here is an example directory structure of a simple application containing a web module, an EJB module, and a client module.


+ converter_1/
|--- converterClient.jar
|--+ META-INF/
|  |--- MANIFEST.MF
|  |--- application.xml
|  |--- sun-application.xml
|--+ war-ic_war/
|  |--- index.jsp
|  |--+ META-INF/
|  |  |--- MANIFEST.MF
|  |--+ WEB-INF/
|     |--- web.xml
|     |--- sun-web.xml
|--+ ejb-jar-ic_jar/
|  |--- Converter.class
|  |--- ConverterBean.class
|  |--- ConverterHome.class
|  |--+ META-INF/
|     |--- MANIFEST.MF
|     |--- ejb-jar.xml
|     |--- sun-ejb-jar.xml
|--+ app-client-ic_jar/
   |--- ConverterClient.class
   |--+ META-INF/
      |--- MANIFEST.MF
      |--- application-client.xml
      |--- sun-application-client.xml

Here is an example directory structure of an individually deployed connector module.


+ MyConnector/
|--- readme.html
|--- ra.jar
|--- client.jar
|--- win.dll
|--- solaris.so
|--+ META-INF/
   |--- MANIFEST.MF
   |--- ra.xml

Runtime Environments

Whether you deploy an individual module or an application, deployment affects both the file system and the server configuration.

Module Runtime Environment

The following figure illustrates the environment for individually deployed module-based deployment.

Figure 3–3 Module runtime environment

After deployment, a module is represented in domain.xml as an ejb-module element and expanded in a directory under j2ee-modules.

For file system entries, modules are extracted as follows:

domain-dir/applications/j2ee-modules/module-name
domain-dir/generated/ejb/j2ee-modules/module-name
domain-dir/generated/jsp/j2ee-modules/module-name

The applications directory contains the directory structures described in Directory Structure. The generated/ejb directory contains the stubs and ties that an ACC client needs to access the module; the generated/jsp directory contains compiled JSP files.

Lifecycle modules (see Chapter 10, Developing Lifecycle Listeners) are extracted as follows:

domain-dir/applications/lifecycle-modules/module-name

Configuration entries are added in the domain.xml file as follows:

<server>
   <applications>
      <type-module>
         ...module configuration...
      </type-module>
   </applications>
</server>

The type of the module in domain.xml can be lifecycle, ejb, web, or connector. For details about domain.xml, see the Sun Java System Application Server Platform Edition 8.2 Administration Reference.

Application Runtime Environment

The following figure illustrates the environment for application-based deployment.

Figure 3–4 Application runtime environment

After deployment, an application is represented in domain.xml as a j2ee-application element and expanded in a directory under j2ee-apps.

For file system entries, applications are extracted as follows:

domain-dir/applications/j2ee-apps/app-name
domain-dir/generated/ejb/j2ee-apps/app-name
domain-dir/generated/jsp/j2ee-apps/app-name

The applications directory contains the directory structures described in Directory Structure. The generated/ejb directory contains the stubs and ties that an ACC client needs to access the module; the generated/jsp directory contains compiled JSP files.

Configuration entries are added in the domain.xml file as follows:

<server>
   <applications>
      <j2ee-application>
         ...application configuration...
      </j2ee-application>
   </applications>
</server>

For details about domain.xml, see the Sun Java System Application Server Platform Edition 8.2 Administration Reference.

Classloaders

Understanding Application Server classloaders can help you determine where and how you can position supporting JAR and resource files for your modules and applications.

In a Java Virtual Machine (JVM), the classloaders dynamically load a specific Java class file needed for resolving a dependency. For example, when an instance of java.util.Enumeration needs to be created, one of the classloaders loads the relevant class into the environment. This section includes the following topics:

The Classloader Hierarchy

Classloaders in the Application Server runtime follow a hierarchy that is illustrated in the following figure and fully described in Table 3–3.

Figure 3–5 Classloader runtime hierarchy

Figure shows the classloader runtime hierarchy.

Table 3–3 Sun Java System Application Server Classloaders

Classloader  

Description  

Bootstrap

The Bootstrap Classloader loads all the JDK classes. It is parent to the System Classloader. 

System

The System Classloader loads most of the core Application Server classes. It is parent to the Common Classloader. It is created based on the classpath-prefix, server-classpath, and classpath-suffix attributes of the java-config element in the domain.xml file. The environment classpath is included if env-classpath-ignored="false" is set in the java-config element.

Common

The Common Classloader loads into the system classpath classes in the domain-dir/lib/classes directory, followed by JAR and ZIP files in the domain-dir/lib directory. It is parent to the Connector Classloader. No special classpath settings are required. The existence of these directories is optional; if they don’t exist, the Common Classloader is not created.

Connector

The Connector Classloader is a single class loader instance that loads individually deployed connector modules, which are shared across all applications. It is parent to the LifeCycleModule Classloader and the EJB Classloader. 

LifeCycleModule

The LifeCycleModule Classloader is the parent class loader for lifecycle modules. Each lifecycle module’s classpath is used to construct its own class loader. 

EJB

The EJB Classloader loads the enabled EJB classes in a specific enabled EJB module or J2EE application. One instance of this class loader is present in each class loader universe. The EJB Classloader is created with a list of URLs that point to the locations of the classes it needs to load. It is parent to the Web Classloader. 

Web

The Web Classloader loads the servlets and other classes in a specific enabled web module or J2EE application. One instance of this class loader is present in each class loader universe. The Web Classloader is created with a list of URLs that point to the locations of the classes it needs to load. It is parent to the JSP Engine Classloader. 

JSP Engine

The JSP Engine Classloader loads compiled JSP classes of enabled JSP files. One instance of this class loader is present in each class loader universe. The JSP Engine Classloader is created with a list of URLs that point to the locations of the classes it needs to load. 

Note that this is not a Java inheritance hierarchy, but a delegation hierarchy. In the delegation design, a class loader delegates classloading to its parent before attempting to load a class itself. A class loader parent can be either the System Classloader or another custom class loader. If the parent class loader can’t load a class, the findClass() method is called on the class loader subclass. In effect, a class loader is responsible for loading only the classes not available to the parent.

The Servlet specification recommends that the Web Classloader look in the local class loader before delegating to its parent. You can make the Web Classloader follow the delegation model in the Servlet specification by setting delegate="false" in the class-loader element of the sun-web.xml file. It’s safe to do this only for a web module that does not interact with any other modules.

The default value is delegate="true", which causes the Web Classloader to delegate in the same manner as the other classloaders. You must use delegate="true" for a web application that accesses EJB components or that acts as a web service client or endpoint. For details about sun-web.xml, see The sun-web.xml File.

Classloader Universes

Access to components within applications and modules installed on the server occurs within the context of isolated class loader universes, each of which has its own EJB, Web, and JSP Engine classloaders.

Note –

A resource such as a file that is accessed by a servlet, JSP, or EJB component must be in a directory pointed to by the class loader’s classpath. For example, the web class loader’s classpath includes these directories:

module-name/WEB-INF/classes
module-name/WEB-INF/lib

If a servlet accesses a resource, it must be in one of these directories or it is not loaded.

Note –

In iPlanet Application Server 6.x, individually deployed modules shared the same class loader. In subsequent Application Server versions, each individually deployed module has its own class loader universe.

Circumventing Classloader Isolation

Since each application or individually deployed module class loader universe is isolated, an application or module cannot load classes from another application or module. This prevents two similarly named classes in different applications from interfering with each other.

To circumvent this limitation for libraries, utility classes, or individually deployed modules accessed by more than one application, you can include the relevant path to the required classes in one of these ways:

Using the System Classloader

To use the System Classloader, do one of the following, then restart the server:

Using the System Classloader makes an application or module accessible to any other application or module across the domain.

Using the Common Classloader

To use the Common Classloader, copy the JAR and ZIP files into the domain-dir/lib directory or copy the .class files into the domain-dir/lib/classes directory, then restart the server.

Using the Common Classloader makes an application or module accessible to any other application or module across the domain.

Using the Java Optional Package Mechanism

To use the Java optional package mechanism, copy the JAR and ZIP files into the domain-dir/lib/ext directory, then restart the server.

Using the Java optional package mechanism makes an application or module accessible to any other application or module across the domain.

For example, this is the recommended way of adding JDBC drivers to the Application Server. For a list of the JDBC drivers currently supported by the Application Server, see the Sun Java System Application Server Platform Edition 8.2 Release Notes. For configurations of supported and other drivers, see Configurations for Specific JDBC Drivers.

Packaging the Client JAR for One Application in Another Application

By packaging the client JAR for one application in a second application, you allow an EJB or web component in the second application to call an EJB component in the first (dependent) application, without making either of them accessible to any other application or module.

As an alternative for a production environment, you can have the Common Classloader load client JAR of the dependent application as described in Using the Common Classloader restart the server to make the dependent application accessible, and it is accessible across the domain.

ProcedureTo package the client JAR for one application in another application

  1. Deploy the dependent application.

  2. Add the dependent application’s client JAR file to the calling application.

    • For a calling EJB component, add the client JAR file at the same level as the EJB component. Then add a Class-Path entry to the MANIFEST.MF file of the calling EJB component. The Class-Path entry has this syntax:

      Class-Path: filepath1.jar filepath2.jar ...

      Each filepath is relative to the directory or JAR file containing the MANIFEST.MF file. For details, see the J2EE specification, section 8.1.1.2, “Dependencies.”

    • For a calling web component, add the client JAR file under the WEB-INF/lib directory.

  3. If you need to package the client JAR with both the EJB and web components, set delegate="true" in the class-loader element of the sun-web.xml file.

    This changes the Web Classloader so it follows the standard class loader delegation model and delegates to its parent before attempting to load a class itself.

    For most applications, packaging the client JAR file with the calling EJB component is sufficient. You do not need to package the client JAR file with both the EJB and web components unless the web component is directly calling the EJB component in the dependent application.

  4. Deploy the calling application.

    The calling EJB or web component must specify in its sun-ejb-jar.xml or sun-web.xml file the JNDI name of the EJB component in the dependent application. Using an ejb-link mapping does not work when the EJB component being called resides in another application.

Assembling Modules and Applications

Assembling (or packaging) modules and applications in Application Server conforms to all of the customary J2EE-defined specifications. The only difference is that when you assemble in Application Server, you include Application Server specific deployment descriptors that enhance the functionality of the Application Server.

For example, when you assemble an EJB JAR module, you must create two deployment descriptor files with these names: ejb-jar.xml and sun-ejb-jar.xml (both required). If the EJB component is an entity bean with container-managed persistence, you can also create a .dbschema file and a sun-cmp-mapping.xml file, but these are not required. For more information about sun-ejb-jar.xml and sun-cmp-mapping.xml, see Appendix A, Deployment Descriptor Files.

Note –

According to the J2EE specification, section 8.1.1.2, “Dependencies,” you cannot package utility classes within an individually deployed EJB module. Instead, package the EJB module and utility JAR within an application using the JAR Extension Mechanism Architecture. For other alternatives, see Circumventing Classloader Isolation.

The Application Server provides these tools for assembling and verifying a module or an application:

deploytool

You can use the deploytool, provided with the Application Server, to assemble J2EE applications and modules, configure deployment parameters, perform simple static checks, and deploy the final result. For more information about using the deploytool, see the J2EE 1.4 Tutorial at http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html.

Apache Ant

Ant can help you assemble and deploy modules and applications. For details, see asant Assembly and Deployment Tool.

NetBeans IDE

You can use the NetBeans IDE to assemble J2EE applications and modules. For more information about using the NetBeans IDE, see http://www.netbeans.org.

The Deployment Descriptor Verifier

The verifier tool validates both J2EE and Application Server specific deployment descriptors against their corresponding DTD files and gives errors and warnings if a module or application is not J2EE and Application Server compliant. You can verify deployment descriptors in EAR, WAR, RAR, and JAR files.

The verifier tool is not simply an XML syntax verifier. Rules and interdependencies between various elements in the deployment descriptors are verified. Where needed, user application classes are introspected to apply validation rules.

The verifier is integrated into Application Server deployment, the deploytool, and the sun-appserv-deploy Ant task. You can also run it as a stand-alone utility from the command line. The verifier is located in the install-dir/bin directory.

When you run the verifier during Application Server deployment, the output of the verifier is written to the tempdir/verifier-results/ directory, where tempdir is the temporary directory defined in the operating system. Deployment fails if any failures are reported during the verification process. The verifier also logs information about verification progress to the standard output.

For details on all the assertions tested by the verifier, see the assertions documentation provided at http://java.sun.com/j2ee/avk/index.html.

Tip –

Using the verifier tool can help you avoid runtime errors that are difficult to debug.

This section covers the following topics:

Command Line Syntax

The verifier tool’s syntax is as follows:

verifier [options] file

The file can be an EAR, WAR, RAR, or JAR file.

The following table shows the options for the verifier tool.

Table 3–4 Verifier Options

Short Form  

Long Form  

Description  

-v

--verbose

Turns on verbose mode. 

-d output-dir

--destdir

Writes test results to the output-dir, which must already exist. By default, the results files are created in the current directory.

-r level

--reportlevel level

Sets the output report level to one of the following values:

  • a or all - Reports all results. This is the default in both verbose and non verbose modes.

  • w or warnings - Reports only warning and failure results.

  • f or failures - Reports only failure results.

-n

--notimestamp

Does not append the timestamp to the output file name. 

-?

--help

Displays help for the verifier command. If you use this option, you do not need to specify an EAR, WAR, RAR, or JAR file. 

-V

--version

Displays the verifier tool version. If you use this option, you do not need to specify an EAR, WAR, RAR, or JAR file. 

-u

--gui

Opens a graphical interface for performing verification. If you use this option, you do not need to specify an EAR, WAR, RAR, or JAR file. For more information, see the verifier online help. 

For example, the following command runs the verifier in verbose mode and writes all the results of static verification of the ejb.jar file to the output directory ResultsDir:

verifier -v -r a -d ResultsDir ejb.jar

The results files are ejb.jar_verifier.timestamp.txt and ejb.jar_verifier.timestamp.xml. The format of the timestamp is yyyyMMddhhmmss.

If the verifier runs successfully, a result code of 0 is returned. This does not mean that no verification errors occurred. A nonzero error code is returned if the verifier fails to run.

Ant Integration

You can integrate the verifier into an Ant build file as a target and use the Ant call feature to call the target each time an application or module is assembled. This is because the main method in com.sun.enterprise.tools.verifier.Verifier is callable from user Ant scripts. The main method accepts the arguments described in Table 3–4.

Example code for an Ant verify target is as follows:

<target name="verify">
 <echo message="Verification Process for ${testfile}"/>
 <java classname="com.sun.enterprise.tools.verifier.Verifier"
		 fork="yes">
	 <sysproperty key="com.sun.enterprise.home"
		 value="${appserv.home}"/>
	 <sysproperty key="verifier.xsl"
		 value="${appserv.home}/verifier/config" />
	 <!-- uncomment the following for verbose output -->
	 <!--<arg value="-v"/>-->
	 <arg value="${assemble}/${ejbjar}" />
	 <classpath path="${appserv.cpath}:${java.class.path}"/>
 </java>
</target>

Sample Results Files

Here is a sample results XML file:

<static-verification>
 <ejb>
	 <failed>
		 <test>
			 <test-name>
tests.ejb.session.TransactionTypeNullForContainerTX
			</test-name>
			 <test-assertion>
Session bean with bean managed transaction demarcation test
			</test-assertion>
			 <test-description>
For [ TheGreeter ] Error: Session Beans [ TheGreeter ] with 
[ Bean ] managed transaction demarcation should not have 
container transactions defined.
			 </test-description>
		 </test>
	 </failed>
 </ejb>
...
</static-verification>

Here is a sample results TXT file:

---------------------------
STATIC VERIFICATION RESULTS
---------------------------
----------------------------------
NUMBER OF FAILURES/WARNINGS/ERRORS
----------------------------------

# of Failures : 3
# of Warnings : 6
# of Errors : 0
-----------------------------
RESULTS FOR EJB-RELATED TESTS
-----------------------------
--------------
FAILED TESTS :
--------------

Test Name : tests.ejb.session.TransactionTypeNullForContainerTX
Test Assertion : Session bean with bean managed transaction demarcation test
Test Description : For [ TheGreeter ]
Error: Session Beans [ TheGreeter ] with [ Bean ] managed transaction 
demarcation should not have container transactions defined.

...
---------------
PASSED TESTS :
---------------

Test Name : tests.ejb.session.ejbcreatemethod.EjbCreateMethodStatic
Test Assertion : Each session Bean must have at least one non-static 
ejbCreate method test
Test Description : For [ TheGreeter ] For EJB Class 
[ samples.helloworld.ejb.GreeterEJB ] method [ ejbCreate ] 
[ samples.helloworld.ejb.GreeterEJB ] properly declares non-static 
ejbCreate(...) method.

...
-----------
WARNINGS :
-----------

Test Name : tests.ejb.businessmethod.BusinessMethodException
Test Assertion : Enterprise bean business method throws RemoteException test
Test Description :

Test Name : tests.ejb.ias.beanpool.IASEjbBeanPool
Test Assertion :
Test Description : WARNING [IAS-EJB ejb] : bean-pool should be defined for 
Stateless Session and Message Driven Beans

...
---------------------
NOTAPPLICABLE TESTS :
---------------------

Test Name : tests.ejb.entity.pkmultiplefield.PrimaryKeyClassFieldsCmp
Test Assertion : Ejb primary key class properly declares all class fields 
within subset of the names of the container-managed fields test.
Test Description : For [ TheGreeter ] class com.sun.enterprise.tools.
verifier.tests.ejb.entity.pkmultiplefield.PrimaryKeyClassFieldsCmp 
expected Entity bean, but called with Session.

Test Name : tests.ejb.entity.ejbcreatemethod.EjbCreateMethodReturn
Test Assertion : Each entity Bean can have zero or more ejbCreate 
methods which return primary key type test
Test Description : For [ TheGreeter ] class com.sun.enterprise.tools.
verifier.tests.ejb.entity.ejbcreatemethod.EjbCreateMethodReturn 
expected Entity bean, but called with Session bean.

...
-----------------------------------
RESULTS FOR OTHER XML-RELATED TESTS
-----------------------------------
---------------
PASSED TESTS :
---------------

Test Name : tests.dd.ParseDD
Test Assertion : Test parses the deployment descriptor using a SAX 
parser to avoid the dependency on the DOL
Test Description : PASSED [EJB] : [ remote ] and [ home ] tags present.
PASSED [EJB]: session-type is Stateless.
PASSED [EJB]: trans-attribute is NotSupported.
PASSED [EJB]: transaction-type is Bean.

...

Deploying Modules and Applications

This section describes the different ways to deploy J2EE applications and modules to the Application Server. It covers the following topics:

Deployment Errors

If an error occurs during deployment, the application or module is not deployed. If a module within an application contains an error, the entire application is not deployed. This prevents a partial deployment that could leave the server in an inconsistent state.

The Deployment Life Cycle

After an application is initially deployed, it can be modified and reloaded, redeployed, disabled, re-enabled, and finally undeployed (removed from the server). This section covers the following topics related to the deployment life cycle:

Note –

You can overwrite a previously deployed application by using the --force option of asadmin deploy or by checking the appropriate box in the Administration Console during deployment. However, you must remove a preconfigured resource before you can update it.

Dynamic Deployment

You can deploy, redeploy, and undeploy an application or module without restarting the server. This is called dynamic deployment. Although primarily for developers, dynamic deployment can be used in operational environments to bring new applications and modules online without requiring a server restart.

Whenever a redeployment is done, the sessions at that transit time become invalid. The client must restart the session.

Disabling a Deployed Application or Module

You can disable a deployed application or module without removing it from the server. Disabling an application makes it inaccessible to clients.

To disable an application or module using the asadmin disable command, see the Sun Java System Application Server Platform Edition 8.2 Reference Manual.

ProcedureTo disable an application or module in the Administration Console

  1. Open the Applications component.

  2. Go to the page for the type of application or module.

    For example, for a web application, go to the Web Applications page.

  3. Click on the name of the application or module you wish to disable.

  4. Uncheck the Status Enabled box.

See Also

For details, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

Dynamic Reloading

If dynamic reloading is enabled (it is by default), you do not have to redeploy an application or module when you change its code or deployment descriptors. All you have to do is copy the changed JSP or class files into the deployment directory for the application or module. The server checks for changes periodically and redeploys the application, automatically and dynamically, with the changes.

This is useful in a development environment, because it allows code changes to be tested quickly. In a production environment, however, dynamic reloading might degrade performance. In addition, whenever a reload is done, the sessions at that transit time become invalid. The client must restart the session.

ProcedureTo enable dynamic reloading in the Administration Console

  1. Select the Application Settings component under the relevant configuration.

  2. Check the Reload Enabled box to enable dynamic reloading.

  3. Enter a number of seconds in the Reload Poll Interval field.

    This sets the interval at which applications and modules are checked for code changes and dynamically reloaded. The default is 2.

See Also

For details, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

ProcedureTo reload code or deployment descriptor changes

  1. Create an empty file named .reload at the root of the deployed application or module.

    For an application:

    domain-dir/applications/j2ee-apps/app-name/.reload

    For an individually deployed module:

    domain-dir/applications/j2ee-modules/module-name/.reload

  2. Explicitly update the .reload file’s timestamp (touch .reload in UNIX) each time you make changes.

Automatic Deployment

Automatic deployment, also called autodeployment, involves copying an application or module file (JAR, WAR, RAR, or EAR) into a special directory, where it is automatically deployed by the Application Server. To undeploy an automatically deployed application or module, simply remove its file from the special autodeployment directory. This is useful in a development environment, because it allows new code to be tested quickly.

Autodeployment is enabled by default.

ProcedureTo enable and configure or to disable autodeployment

  1. Select the Application Settings component under the relevant configuration.

  2. Check the Auto Deploy Enabled box to enable autodeployment, or uncheck this box to disable autodeployment.

  3. Enter a number of seconds in the Auto Deploy Poll Interval field.

    This sets the interval at which applications and modules are checked for code changes and dynamically reloaded. The default is 2.

  4. You can change the Auto Deploy Directory if you like.

    You can enter an absolute or relative path. A relative path is relative to domain-dir. The default is domain-dir/autodeploy.

  5. You can check the Verifier Enabled box to verify your deployment descriptor files. This is optional.

    For details about the verifier, see The Deployment Descriptor Verifier.

  6. Check the Precompile Enabled box to precompile any JSP files.

See Also

For details, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

Tools for Deployment

This section discusses the various tools that can be used to deploy modules and applications. The deployment tools include:

Apache Ant

Ant can help you assemble and deploy modules and applications. For details, see asant Assembly and Deployment Tool.

The deploytool

You can use the deploytool, provided with Application Server, to assemble J2EE applications and modules, configure deployment parameters, perform simple static checks, and deploy the final result. For more information about using the deploytool, see the J2EE 1.4 Tutorial at http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html.

JSR 88

You can write your own JSR 88 client to deploy applications to the Application Server. For more information, see the JSR 88 page at http://jcp.org/en/jsr/detail?id=88.

See Naming Standards for application and module naming considerations.

The asadmin Command

You can use the asadmin deploy or asadmin deploydir command to deploy or undeploy applications and individually deployed modules on local servers. For details, see the Sun Java System Application Server Platform Edition 8.2 Reference Manual.

To deploy a lifecycle module, see Deploying a Lifecycle Module.

Note –

On Windows, if you are deploying a directory on a mapped drive, you must be running the Application Server as the same user to which the mapped drive is assigned, or the Application Server won’t see the directory.

The Administration Console

You can use the Administration Console to deploy modules and applications to both local and remote Application Server sites.

ProcedureTo use the Administration Console for deployment

  1. Open the Applications component.

  2. Go to the page for the type of application or module.

    For example, for a web application, go to the Web Applications page.

  3. Click on the Deploy button.

    You can also undeploy, enable, or disable an application or module from this page.

See Also

For details, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

To deploy a lifecycle module, see Deploying a Lifecycle Module.

Deployment by Module or Application

You can deploy applications or individual modules that are independent of applications. The runtime and file system implications of application-based or individual module-based deployment are described in Runtime Environments.

Individual module-based deployment is preferable when components need to be accessed by:

Modules can be combined into an EAR file and then deployed as a single module. This is similar to deploying the modules of the EAR independently.

Deploying a WAR Module

You deploy a WAR module as described in Tools for Deployment.

You can precompile JSP files during deployment by checking the appropriate box in the Administration Console or by using the --precompilejsp option of the asadmin deploy or asadmin deploydir command. The sun-appserv-deploy and sun-appserv-jspc Ant tasks also allow you to precompile JSP files.

You can keep the generated source for JSP files by adding the -keepgenerated flag to the jsp-config element in sun-web.xml. If you include this property when you deploy the WAR module, the generated source is kept in domain-dir/generated/jsp/j2ee-apps/app-name/module-name if it is in an application or domain-dir/generated/jsp/j2ee-modules/module-name if it is in an individually deployed web module.

For more information about JSP precompilation, see Options for Compiling JSP Files jsp-config.

Deploying an EJB JAR Module

You deploy an EJB JAR module as described in Tools for Deployment.

You can keep the generated source for stubs and ties by adding the -keepgenerated flag to the rmic-options attribute of the java-config element in domain.xml. If you include this flag when you deploy the EJB JAR module, the generated source is kept in domain-dir/generated/ejb/j2ee-apps/app-name/module-name if it is in an application or domain-dir/generated/ejb/j2ee-modules/module-name if it is in an individually deployed EJB JAR module. For more information about the -keepgenerated flag, see the Sun Java System Application Server Platform Edition 8.2 Administration Reference.

Generation of stubs and ties is performed asynchronously, so unless you request their generation during deployment (for example, using the --retrieve option of the asadmin deploy command), stubs and ties are not guaranteed to be available immediately after deployment. You can use the asadmin get-client-stubs command to retrieve the stubs and ties whether or not you requested their generation during deployment. For details, see the Sun Java System Application Server Platform Edition 8.2 Reference Manual.

Deploying a Lifecycle Module

For general information about lifecycle modules, see Chapter 10, Developing Lifecycle Listeners.

You can deploy a lifecycle module using the following tools:

Note –

If the is-failure-fatal setting is set to true (the default is false), lifecycle module failure prevents server initialization or startup, but not shutdown or termination.

Deploying an Application Client

Deployment is only necessary for application clients that communicate with EJB components.

ProcedureTo deploy an application client

  1. Assemble the necessary client files.

  2. Assemble the EJB components to be accessed by the client.

  3. Package the client and EJB components together in an application.

  4. Deploy the application as described in Tools for Deployment.

  5. Retrieve the client JAR file.

    The client JAR file contains the ties and necessary classes for the ACC client.

    You can use the --retrieve option to get the client JAR file.

    You can also use the asadmin get-client-stubs command to retrieve the stubs and ties whether or not you requested their generation during deployment. For details, see the Sun Java System Application Server Platform Edition 8.2 Reference Manual.

  6. Copy the client JAR file to the client machine, and set the APPCPATH environment variable on the client to point to this JAR.

Next Steps

To execute the client on the Application Server machine to test it, use the appclient script in the install-dir/bin directory.The only required option is -client. For example:

appclient -client converterClient.jar

The -xml parameter specifies the location of the sun-acc.xml file.

See Also

For more detailed information about the appclient script, see Chapter 8, Developing Java Clients.

ProcedureTo prepare another machine for executing an application client

  1. You can use the package-appclient script in the install-dir/bin directory to create the ACC package JAR file. This is optional.

    This JAR file is created in the install-dir /lib/appclient directory.

  2. Copy the ACC package JAR file to the client machine and unjar it.

  3. Configure the sun-acc.xml file.

    This file is located in the appclient/appserv/lib/appclient directory by default if you used the package-appclient script.

  4. Configure the asenv.conf (asenv.bat on Windows) file.

    This file is located in appclient/appserv/bin by default if you used the package-appclient script.

  5. Copy the client JAR file to the client machine.

    You are now ready to execute the client.

See Also

For more detailed information about the package-appclient script, see Chapter 8, Developing Java Clients.

Deploying a J2EE CA Resource Adapter

You deploy a connector module as described in Tools for Deployment. After deploying the module, you must configure it as described in Chapter 9, Developing Connectors.

Access to Shared Frameworks

When J2EE applications and modules use shared framework classes (such as utility classes and libraries) the classes can be put in the path for the System Classloader or the Common Classloader rather than in an application or module. If you assemble a large, shared library into every module that uses it, the result is a huge file that takes too long to register with the server. In addition, several versions of the same class could exist in different classloaders, which is a waste of resources. For more information, see Circumventing Classloader Isolation.

asant Assembly and Deployment Tool

Apache Ant 1.6.5 is provided with Application Server and can be launched from the bin directory using the command asant. The Application Server also provides server-specific tasks for deployment, which are described in this section.

Make sure you have done these things before using asant:

This section covers the following asant-related topics:

For more information about Ant, see the Apache Software Foundation web site at http://ant.apache.org/.

For information about standard Ant tasks, see the Ant documentation at http://ant.apache.org/manual/.

asant Tasks for Sun Java System Application Server

Use the asant tasks provided by the Application Server for assembling, deploying, and undeploying modules and applications, and for configuring the server. The tasks are as follows:

sun-appserv-deploy

Deploys any of the following.

Subelements

The following table describes subelements for the sun-appserv-deploy task. These are objects upon which this task acts.

Table 3–5 sun-appserv-deploy Subelements

Element  

Description  

component

A component to be deployed. 

fileset

A set of component files that match specified parameters. 

Attributes

The following table describes attributes for the sun-appserv-deploy task.

Table 3–6 sun-appserv-deploy Attributes

Attribute  

Default  

Description  

file

none 

(optional if a component or fileset subelement is present, otherwise required) The component to deploy. If this attribute refers to a file, it must be a valid archive. If this attribute refers to a directory, it must contain a valid archive in which all components have been exploded. If upload is set to false, this must be an absolute path on the server machine.

name

file name without extension 

(optional) The display name for the component being deployed. 

type

determined by extension 

(optional) Deprecated. 

force

true

(optional) If true, the component is overwritten if it already exists on the server. If false, sun-appserv-deploy fails if the component exists.

retrievestubs

client stubs not saved 

(optional) The directory where client stubs are saved. This attribute is inherited by nested component elements.

precompilejsp

false

(optional) If true, all JSP files found in an enterprise application (.ear) or web application (.war) are precompiled. This attribute is ignored for other component types. This attribute is inherited by nested component elements.

verify

false

(optional) If true, syntax and semantics for all deployment descriptors are automatically verified for correctness. This attribute is inherited by nested component elements.

contextroot

file name without extension 

(optional) The context root for a web module (WAR file). This attribute is ignored if the component is not a WAR file. 

dbvendorname

sun-ejb-jar.xml entry

(optional) The name of the database vendor for which tables can be created. Allowed values are db2, mssql, oracle, derby, and sybase, case-insensitive.

If not specified, the value of the database-vendor-name attribute in sun-ejb-jar.xml is used.

If no value is specified, a connection is made to the resource specified by the jndi-name subelement of the cmp-resource element in the sun-ejb-jar.xml file, and the database vendor name is read. If the connection cannot be established, or if the value is not recognized, SQL-92 compliance is presumed.

For details, see Generation Options.

createtables

sun-ejb-jar.xml entry

(optional) If true, causes database tables to be created for beans that need them. If false, does not create tables. If not specified, the value of the create-tables-at-deploy attribute in sun-ejb-jar.xml is used.

For details, see Generation Options.

dropandcreatetables

sun-ejb-jar.xml entry

(optional) If true, and if tables were automatically created when this application was last deployed, tables from the earlier deployment are dropped and fresh ones are created.

If true, and if tables were not automatically created when this application was last deployed, no attempt is made to drop any tables. If tables with the same names as those that would have been automatically created are found, the deployment proceeds, but a warning indicates that tables could not be created.

If false, settings of create-tables-at-deploy or drop-tables-at-undeploy in the sun-ejb-jar.xml file are overridden.

For details, see Generation Options.

uniquetablenames

sun-ejb-jar.xml entry

(optional) If true, specifies that table names are unique within each application server domain. If not specified, the value of the use-unique-table-names property in sun-ejb-jar.xml is used.

For details, see Generation Options.

enabled

true

(optional) If true, enables the component.

deploymentplan

none 

(optional) A deployment plan is a JAR file containing Sun-specific descriptors. Use this attribute when deploying an EAR file that lacks Sun-specific descriptors. 

upload

true

(optional) If true, the component is transferred to the server for deployment. If the component is being deployed on the local machine, set upload to false to reduce deployment time. If a directory is specified for deployment, upload must be false.

virtualservers

default virtual server only 

(optional) A comma-separated list of virtual servers to be deployment targets. This attribute applies only to application (.ear) or web (.war) components and is ignored for other component types.

user

admin

(optional) The user name used when logging into the application server. 

password

none 

(optional) Deprecated, use passwordfile instead. The password used when logging into the application server.

passwordfile

none 

(optional) File containing passwords. The password from this file is retrieved for communication with the application server. If both password and passwordfile are specified, passwordfile takes precedence.

host

localhost

(optional) Target server. When deploying to a remote server, use the fully qualified host name. 

port

4848

(optional) The administration port on the target server. 

asinstalldir

see description 

(optional) The installation directory for the local Application Server installation, which is used to find the administrative classes. If not specified, the command checks to see if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath.

sunonehome

see description 

(optional) Deprecated. Use asinstalldir instead.

Examples

Here is a simple application deployment script with many implied attributes:

<sun-appserv-deploy
file="${assemble}/simpleapp.ear"
passwordfile="${passwordfile}" />

Here is an equivalent script showing all the implied attributes:

<sun-appserv-deploy
 file="${assemble}/simpleapp.ear"
 name="simpleapp"
 force="true"
 precompilejsp="false"
 verify="false"
 upload="true"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 asinstalldir="${asinstalldir}" />

This example deploys multiple components to the same Application Server running on a remote server:

<sun-appserv-deploy passwordfile="${passwordfile}" host="greg.sun.com"
		 asinstalldir="/opt/sun" >
 <component file="${assemble}/simpleapp.ear"/>
 <component file="${assemble}/simpleservlet.war"
	 contextroot="test"/>
 <component file="${assemble}/simplebean.jar"/>
</sun-appserv-deploy>

This example deploys the same components as the previous example because the three components match the fileset criteria, but note that it’s not possible to set some component-specific attributes. All component-specific attributes (name and contextroot) use their default values.

<sun-appserv-deploy passwordfile="${passwordfile}" host="greg.sun.com"
		 asinstalldir="/opt/sun" >
 <fileset dir="${assemble}" includes="**/*.?ar" />
</sun-appserv-deploy>

sun-appserv-undeploy

Undeploys any of the following.

Subelements

The following table describes subelements for the sun-appserv-undeploy task. These are objects upon which this task acts.

Table 3–7 sun-appserv-undeploy Subelements

Element  

Description  

component

A component to be deployed. 

fileset

A set of component files that match specified parameters. 

Attributes

The following table describes attributes for the sun-appserv-undeploy task.

Table 3–8 sun-appserv-undeploy Attributes

Attribute  

Default  

Description  

name

file name without extension 

(optional if a component or fileset subelement is present or the file attribute is specified, otherwise required) The display name for the component being undeployed.

file

none 

(optional) The component to undeploy. If this attribute refers to a file, it must be a valid archive. If this attribute refers to a directory, it must contain a valid archive in which all components have been exploded. 

type

determined by extension 

(optional) Deprecated. 

droptables

sun-ejb-jar.xml entry

(optional) If true, causes database tables that were automatically created when the bean(s) were last deployed to be dropped when the bean(s) are undeployed. If false, does not drop tables.

If not specified, the value of the drop-tables-at-undeploy attribute in sun-ejb-jar.xml is used.

For details, see Generation Options.

cascade

false

(optional) If true, deletes all connection pools and connector resources associated with the resource adapter being undeployed.

If false, undeployment fails if any pools or resources are still associated with the resource adapter.

This attribute is applicable to connectors (resource adapters) and applications with connector modules. 

user

admin

(optional) The user name used when logging into the application server. 

password

none 

(optional) Deprecated, use passwordfile instead. The password used when logging into the application server.

passwordfile

none 

(optional) File containing passwords. The password from this file is retrieved for communication with the application server. If both password and passwordfile are specified, passwordfile takes precedence.

host

localhost

(optional) Target server. When deploying to a remote server, use the fully qualified host name. 

port

4848 

(optional) The administration port on the target server. 

asinstalldir

see description 

(optional) The installation directory for the local Application Server installation, which is used to find the administrative classes. If not specified, the command checks to see if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath.

sunonehome

see description 

(optional) Deprecated. Use asinstalldir instead.

Examples

Here is a simple application undeployment script with many implied attributes:

<sun-appserv-undeploy name="simpleapp" passwordfile="${passwordfile}" />

Here is an equivalent script showing all the implied attributes:

<sun-appserv-undeploy
 name="simpleapp"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 asinstalldir="${asinstalldir}" />

This example demonstrates using the archive files (EAR and WAR, in this case) for the undeployment, using the component name (for undeploying the EJB component in this example), and undeploying multiple components.

<sun-appserv-undeploy passwordfile="${passwordfile}">
 <component file="${assemble}/simpleapp.ear"/>
 <component file="${assemble}/simpleservlet.war"/>
 <component name="simplebean" />
</sun-appserv-undeploy>

sun-appserv-component

Enables or disables the following J2EE component types that have been deployed to the Application Server.

You don’t need to specify the archive to enable or disable a component: only the component name is required. You can use the component archive, however, because it implies the component name.

Subelements

The following table describes subelements for the sun-appserv-component task. These are objects upon which this task acts.

Table 3–9 sun-appserv-component Subelements

Element  

Description  

component

A component to be deployed. 

fileset

A set of component files that match specified parameters. 

Attributes

The following table describes attributes for the sun-appserv-component task.

Table 3–10 sun-appserv-component Attributes

Attribute  

Default  

Description  

action

none 

The control command for the target application server. Valid values are enable and disable.

name

file name without extension 

(optional if a component or fileset subelement is present or the file attribute is specified, otherwise required) The display name for the component being enabled or disabled.

file

none 

(optional) The component to enable or disable. If this attribute refers to a file, it must be a valid archive. If this attribute refers to a directory, it must contain a valid archive in which all components have been exploded. 

type

determined by extension 

(optional) Deprecated. 

user

admin

(optional) The user name used when logging into the application server. 

password

none 

(optional) Deprecated, use passwordfile instead. The password used when logging into the application server.

passwordfile

none 

(optional) File containing passwords. The password from this file is retrieved for communication with the application server. If both password and passwordfile are specified, passwordfile takes precedence.

host

localhost

(optional) Target server. When enabling or disabling a remote server, use the fully qualified host name. 

port

4848

(optional) The administration port on the target server. 

asinstalldir

see description 

(optional) The installation directory for the local Application Server installation, which is used to find the administrative classes. If not specified, the command checks to see if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath.

sunonehome

see description 

(optional) Deprecated. Use asinstalldir instead.

Examples

Here is a simple example of disabling a component:

<sun-appserv-component
 action="disable"
 name="simpleapp"
 passwordfile="${passwordfile}" />

Here is a simple example of enabling a component:

<sun-appserv-component
 action="enable"
 name="simpleapp"
 passwordfile="${passwordfile}" />

Here is an equivalent script showing all the implied attributes:

<sun-appserv-component
 action="enable"
 name="simpleapp"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 asinstalldir="${asinstalldir}" />

This example demonstrates disabling multiple components using the archive files (EAR and WAR, in this case) and using the component name (for an EJB component in this example).

<sun-appserv-component action="disable" passwordfile="${passwordfile}">
 <component file="${assemble}/simpleapp.ear"/>
 <component file="${assemble}/simpleservlet.war"/>
 <component name="simplebean" />
</sun-appserv-component>

sun-appserv-admin

Enables arbitrary administrative commands and scripts to be executed on the Application Server. This is useful for cases where a specific Ant task hasn’t been developed or a set of related commands are in a single script.

Subelements

none

Attributes

The following table describes attributes for the sun-appserv-admin task.

Table 3–11 sun-appserv-admin Attributes

Attribute  

Default  

Description  

command

none 

(exactly one of these is required: command, commandfile, or explicitcommand) The command to execute. If the user, passwordfile, host, or port attributes are also specified, they are automatically inserted into the command before execution. If any of these options are specified in the command string, the corresponding attribute values are ignored.

commandfile

none 

(exactly one of these is required: command, commandfile, or explicitcommand) Deprecated. The command script to execute. If commandfile is used, the values of all other attributes are ignored. Be sure to end the script referenced by commandfile with the exit command; if you omit exit, the Ant task might appear to hang after the command script is called.

explicitcommand

none 

(exactly one of these is required: command, commandfile, or explicitcommand) The exact command to execute. No command processing is done, and all other attributes are ignored.

user

admin

(optional) The user name used when logging into the application server. 

password

none 

(optional) Deprecated, use passwordfile instead. The password used when logging into the application server.

passwordfile

none 

(optional) File containing passwords. The password from this file is retrieved for communication with the application server. If both password and passwordfile are specified, passwordfile takes precedence.

host

localhost

(optional) Target server. If it is a remote server, use the fully qualified host name. 

port

4848 

(optional) The administration port on the target server. 

asinstalldir

see description 

(optional) The installation directory for the local Application Server installation, which is used to find the administrative classes. If not specified, the command checks to see if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath.

sunonehome

see description 

(optional) Deprecated. Use asinstalldir instead.

Examples

Here is an example of executing the create-jms-dest command:

<sun-appserv-admin command="create-jms-dest --desttype topic">

Here is an example of using commandfile to execute the create-jms-dest command:

<sun-appserv-admin commandfile="create_jms_dest.txt" instance="development">

The create_jms_dest.txt file contains the following:

create-jms-dest --user admin --passwordfile "${passwordfile}" --host 
localhost --port 4848 --desttype topic --target server1 simpleJmsDest

Here is an example of using explicitcommand to execute the create-jms-dest command:

<sun-appserv-admin command="create-jms-dest --user admin --passwordfile 
"${passwordfile}" --host localhost --port 4848 --desttype topic 
--target server1 simpleJmsDest">

sun-appserv-jspc

Precompiles JSP source code into Application Server compatible Java code for initial invocation by Application Server. Use this task to speed up access to JSP files or to check the syntax of JSP source code. You can feed the resulting Java code to the javac task to generate class files for the JSP files.

Subelements

none

Attributes

The following table describes attributes for the sun-appserv-jspc task.

Table 3–12 sun-appserv-jspc Attributes

Attribute  

Default  

Description  

destdir

 

The destination directory for the generated Java source files. 

srcdir

 

(exactly one of these is required: srcdir or webapp) The source directory where the JSP files are located.

webapp

 

(exactly one of these is required: srcdir or webapp) The directory containing the web application. All JSP files within the directory are recursively parsed. The base directory must have a WEB-INF subdirectory beneath it. When webapp is used, sun-appserv-jspc hands off all dependency checking to the compiler.

verbose

2

(optional) The verbosity integer to be passed to the compiler. 

classpath

 

(optional) The classpath for running the JSP compiler. 

classpathref

 

(optional) A reference to the JSP compiler classpath. 

uribase

/

(optional) The URI context of relative URI references in the JSP files. If this context does not exist, it is derived from the location of the JSP file relative to the declared or derived value of uriroot. Only pages translated from an explicitly declared JSP file are affected.

uriroot

see description 

(optional) The root directory of the web application, against which URI files are resolved. If this directory is not specified, the first JSP file is used to derive it: each parent directory of the first JSP file is searched for a WEB-INF directory, and the directory closest to the JSP file that has one is used. If no WEB-INF directory is found, the directory sun-appserv-jspc was called from is used. Only pages translated from an explicitly declared JSP file (including tag libraries) are affected.

package

 

(optional) The destination package for the generated Java classes. 

asinstalldir

see description 

(optional) The installation directory for the local Application Server installation, which is used to find the administrative classes. If not specified, the command checks to see if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath.

sunonehome

see description 

(optional) Deprecated. Use asinstalldir instead.

Example

The following example uses the webapp attribute to generate Java source files from JSP files. The sun-appserv-jspc task is immediately followed by a javac task, which compiles the generated Java files into class files. The classpath value in the javac task must be all on one line with no spaces.

<sun-appserv-jspc
 destdir="${assemble.war}/generated"
 webapp="${assemble.war}"
 classpath="${assemble.war}/WEB-INF/classes"
 asinstalldir="${asinstalldir}" />
<javac
 srcdir="${assemble.war}/WEB-INF/generated"
 destdir="${assemble.war}/WEB-INF/generated"
 debug="on"
 classpath="${assemble.war}/WEB-INF/classes:${asinstalldir}/lib/
   appserv-rt.jar:${asinstalldir}/lib/appserv-ext.jar">
 <include name="**/*.java"/>
</javac>

sun-appserv-update

Enables deployed applications (EAR files) and modules (EJB JAR, RAR, and WAR files) to be updated and reloaded for fast iterative development. This task copies modified class files, XML files, and other contents of the archive files to the appropriate subdirectory of the domain-dir/applications directory, then touches the .reload file to cause dynamic reloading to occur.

This is a local task and must be executed on the same machine as the application server.

Subelements

none

Attributes

The following table describes attributes for the sun-appserv-update task.

Table 3–13 sun-appserv-update Attributes

Attribute  

Default  

Description  

file

none 

The component to update, which must be a valid archive. 

domain

domain1

(optional) The domain in which the application has been previously deployed. 

Example

The following example updates the J2EE application foo.ear, which is deployed to the default domain, domain1.

<sun-appserv-update file="foo.ear"/>

Reusable Subelements

Reusable subelements of the Ant tasks for the Application Server are as follows. These are objects upon which the Ant tasks act.

component

Specifies a J2EE component. Allows a single task to act on multiple components. The component attributes override corresponding attributes in the parent task; therefore, the parent task attributes function as default values.

Subelements

none

Attributes

The following table describes attributes for the component element.

Table 3–14 component Attributes

Attribute  

Default  

Description  

file

none 

(optional if the parent task is sun-appserv-undeploy or sun-appserv-component) The target component. If this attribute refers to a file, it must be a valid archive. If this attribute refers to a directory, it must contain a valid archive in which all components have been exploded. If upload is set to false, this must be an absolute path on the server machine.

name

file name without extension 

(optional) The display name for the component. 

type

determined by extension 

(optional) Deprecated. 

force

true

(applies to sun-appserv-deploy only, optional) If true, the component is overwritten if it already exists on the server. If false, the containing element’s operation fails if the component exists.

precompilejsp

false

(applies to sun-appserv-deploy only, optional) If true, all JSP files found in an enterprise application (.ear) or web application (.war) are precompiled. This attribute is ignored for other component types.

retrievestubs

client stubs not saved 

(applies to sun-appserv-deploy only, optional) The directory where client stubs are saved.

contextroot

file name without extension 

(applies to sun-appserv-deploy only, optional) The context root for a web module (WAR file). This attribute is ignored if the component is not a WAR file.

verify

false

(applies to sun-appserv-deploy only, optional) If true, syntax and semantics for all deployment descriptors is automatically verified for correctness.

Examples

You can deploy multiple components using a single task. This example deploys each component to the same Application Server running on a remote server.

<sun-appserv-deploy passwordfile="${passwordfile}" host="greg.sun.com"
	 asinstalldir="/opt/s1as8" >
<component file="${assemble}/simpleapp.ear"/>
<component file="${assemble}/simpleservlet.war"
	 contextroot="test"/>
<component file="${assemble}/simplebean.jar"/>
</sun-appserv-deploy>

You can also undeploy multiple components using a single task. This example demonstrates using the archive files (EAR and WAR, in this case) and the component name (for the EJB component).

<sun-appserv-undeploy passwordfile="${passwordfile}">
<component file="${assemble}/simpleapp.ear"/
<component file="${assemble}/simpleservlet.war"/>
<component name="simplebean" />
</sun-appserv-undeploy>

You can enable or disable multiple components. This example demonstrates disabling multiple components using the archive files (EAR and WAR, in this case) and the component name (for the EJB component).

<sun-appserv-component action="disable" passwordfile="${passwordfile}">
<component file="${assemble}/simpleapp.ear"/>
<component file="${assemble}/simpleservlet.war"/>
<component name="simplebean" />
</sun-appserv-component>

fileset

Selects component files that match specified parameters. When fileset is included as a subelement, the name and contextroot attributes of the containing element must use their default values for each file in the fileset. For more information, see http://ant.apache.org/manual/CoreTypes/fileset.html.

Chapter 4 Debugging Applications

This chapter gives guidelines for debugging applications in the Sun Java System Application Server. It includes the following sections:

Enabling Debugging

When you enable debugging, you enable both local and remote debugging. To start the server in debug mode, use the --debug option as follows:

asadmin start-domain --debug [domain-name]

You can then attach to the server from the debugger at its default JPDA port, which is 9009. For example, for UNIX systems:

jdb -attach 9009

For Windows:

jdb -connect com.sun.jdi.SocketAttach:port=9009

Application Server debugging is based on the JPDA (Java Platform Debugger Architecture). For more information, see JPDA Options.

You can enable debugging even when the application server is started without the --debug option. This is useful if you start the application server from the Windows Start Menu or if you want to make sure that debugging is always turned on.

ProcedureTo set the server to automatically start up in debug mode

  1. Select the JVM Settings component under the relevant configuration in the Administration Console.

  2. Check the Debug Enabled box.

  3. To specify a different port (from 9009, the default) to use when attaching the JVM to a debugger, specify address= port-number in the Debug Options field.

  4. If you wish to add JPDA options, add any desired JPDA debugging options in Debug Options. See JPDA Options .

See Also

For details, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

JPDA Options

The default JPDA options in Application Server are as follows:

-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=9009

For Windows, you can change dt_socket to dt_shmem.

If you substitute suspend=y, the JVM starts in suspended mode and stays suspended until a debugger attaches to it. This is helpful if you want to start debugging as soon as the JVM starts.

To specify a different port (from 9009, the default) to use when attaching the JVM to a debugger, specify address=port-number.

You can include additional options. A list of JPDA debugging options is available at http://java.sun.com/products/jpda/doc/conninv.html#Invocation.

Generating a Stack Trace for Debugging

You can generate a Java stack trace for debugging as described here if the Application Server is in verbose mode (see Enabling Verbose Mode):

http://developer.java.sun.com/developer/technicalArticles/Programming/Stacktrace/

The stack trace goes to the domain-dir/logs/server.log file and also appears on the command prompt screen.

If the -Xrs flag is set (for reduced signal usage) in the domain.xml file (under jvm-options), comment it out before generating the stack trace. If the -Xrs flag is used, the server might simply dump core and restart when you send the signal to generate the trace. For more about the domain.xml file, see the Sun Java System Application Server Platform Edition 8.2 Administration Reference.

The Java Debugger

The Java Debugger (jdb) helps you find and fix bugs in Java language programs. When using the jdb debugger with the Application Server, you must attach to the server from the debugger at its default JPDA port, which is 9009. For example, for UNIX systems:

jdb -attach 9009

For Windows:

jdb -connect com.sun.jdi.SocketAttach:port=9009

For more information about the jdb debugger, see the following links:

Java Platform Debugger Architecture - The Java Debugger: http://java.sun.com/products/jpda/doc/soljdb.html

Java Platform Debugger Architecture - Connecting with JDB: http://java.sun.com/products/jpda/doc/conninv.html#JDB

You can attach to the Application Server using any JPDA compliant debugger, including that of NetBeans, Sun Java Studio, JBuilder, Eclipse, and so on.

Using an IDE

You can use an IDE (integrated development environment) with the Application Server to take advantage of the IDE's debugging features.

ProcedureTo use the NetBeans IDE for Debugging

The following steps are applicable to the NetBeans 5 IDE and the Sun Java Studio 8 software, which is built on the NetBeans IDE.

  1. Download the latest version of NetBeans from http://www.netbeans.org.

    This site also provides documentation for the NetBeans IDE.

  2. Start the NetBeans IDE.

  3. If an Application Server is not already configured in the NetBeans IDE, perform the following steps:

    1. Select the Runtime tab to display the Runtime window.

    2. Right-click on Servers in the Runtime window.

    3. Select the Add Server command from the menu.

    4. On the first screen, select Sun Java System Application Server in the Server field, and type a name in the Name field. Select Next.

    5. On the second screen, fill in the requested configuration information. In the Domains folder field, use the Browse button to go to the Application Server domain-root-dir directory.

    6. Click Finish.

  4. Create a project (an application or module) in the NetBeans IDE.

  5. Right-click on the project in the component tree and select Debug Project from the menu.

    This stops the Application Server and restarts it in debug mode.

  6. Set break points in your source file in the NetBeans IDE as usual, and run the application.

Sun Java System Message Queue Debugging

Sun Java System Message Queue has a broker logger, which can be useful for debugging JMS, including message-driven bean, applications. You can adjust the logger’s verbosity, and you can send the logger output to the broker’s console using the broker’s -tty option. For more information, see the Sun Java System Message Queue 3.7 UR1 Administration Guide.

Enabling Verbose Mode

If you want to see the server logs and messages printed to System.out on your command prompt screen, you can start the server in verbose mode. This makes it easy to do simple debugging using print statements, without having to view the server.log file every time.

When the server is in verbose mode, messages are logged to the console or terminal window in addition to the log file. In addition, pressing Ctrl-C stops the server and pressing Ctrl-\ (on UNIX platforms) or Ctrl-Break (on Windows platforms) prints a thread dump. On UNIX platforms, you can also print a thread dump using the jstack command (see http://java.sun.com/j2se/1.5.0/docs/tooldocs/share/jstack.html) or the command kill -QUIT process_id.

To start the server in verbose mode, use the --verbose option as follows:

asadmin start-domain --verbose [domain-name]

You can enable verbose mode even when the application server is started without the --verbose option. This is useful if you start the application server from the Windows Start Menu or if you want to make sure that verbose mode is always turned on.

You can set the server to automatically start up in verbose mode using the Administration Console. For details, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

Logging

You can use the Application Server’s log files to help debug your applications. In the Administration Console, select the Application Server component, then click on the Open Log Viewer button in the General Information page. For details about logging, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

Profiling

You can use a profiler to perform remote profiling on the Application Server to discover bottlenecks in server-side performance. This section describes how to configure these profilers for use with the Application Server:

Information about comprehensive monitoring and management support in the JavaTM 2 Platform, Standard Edition (J2SETM platform) version 5.0 is available at http://java.sun.com/j2se/1.5.0/docs/guide/management/index.html.

The HPROF Profiler

HPROF is a simple profiler agent shipped with the Java 2 SDK. It is a dynamically linked library that interacts with the JVMPI and writes out profiling information either to a file or to a socket in ASCII or binary format.

HPROF can present CPU usage, heap allocation statistics, and monitor contention profiles. In addition, it can also report complete heap dumps and states of all the monitors and threads in the Java virtual machine. For more details on the HPROF profiler, see the JDK documentation at http://java.sun.com/j2se/1.4.2/docs/guide/jvmpi/jvmpi.html#hprof.

Once HPROF is enabled using the following instructions, its libraries are loaded into the server process.

ProcedureTo use HPROF profiling on UNIX

  1. Configure the Application Server using the Administration Console:

    1. Select the JVM Settings component under the relevant configuration, then select the Profiler tab.

    2. Edit the following fields:

      • Profiler Name: hprof

      • Profiler Enabled: true

      • Classpath: (leave blank)

      • Native Library Path: (leave blank)

      • JVM Option: For each of these options, select Add, type the option in the Value field, then check its box:

        -Xrunhprof:file=log.txt,options

        Here is an example of options you can use:


        -Xrunhprof:file=log.txt,thread=y,depth=3

        The file option determines where the stack dump is written in Step 2.

        The syntax of HPROF options is as follows:


        -Xrunhprof[:help]|[:option=value,option2=value2, ...]

        Using help lists options that can be passed to HPROF. The output is as follows:


        Hprof usage: -Xrunhprof[:help]|[:<option>=<value>, ...]

Option Name and Value   Description             Default
---------------------   -----------             -------
heap=dump|sites|all     heap profiling          all
cpu=samples|old         CPU usage               off
format=a|b              ascii or binary output  a
file=<file>             write data to file      java.hprof
							   (.txt for ascii)
net=<host>:<port>       send data over a socket write to file
depth=<size>            stack trace depth       4
cutoff=<value>          output cutoff point     0.0001
lineno=y|n              line number in traces?  y
thread=y|n              thread in traces?       n
doe=y|n                 dump on exit?           y

  2. Restart the Application Server. This writes an HPROF stack dump to the file you specified using the file HPROF option in Step 1.

The Optimizeit Profiler

You can purchase OptimizeitTM from Borland at http://www.borland.com/optimizeit.

Once Optimizeit is enabled using the following instructions, its libraries are loaded into the server process.

ProcedureTo enable remote profiling with Optimizeit

  1. Configure your operating system:

    • On Solaris, add Optimizeit-dir/lib to the LD_LIBRARY_PATH environment variable.

    • On Windows, add Optimizeit-dir/lib to the PATH environment variable.

  2. Configure the Application Server using the Administration Console:

    1. Select the JVM Settings component under the relevant configuration, then select the Profiler tab.

    2. Edit the following fields:

      • Profiler Name: optimizeit

      • Profiler Enabled: true

      • Classpath: Optimizeit-dir/lib/optit.jar

      • Native Library Path: Optimizeit-dir/lib

      • JVM Option: For each of these options, select Add, type the option in the Value field, then check its box:


        -DOPTITHOME=Optimizeit-dir  -Xrunpri:startAudit=t 
-Xbootclasspath/p:/Optimizeit-dir/lib/oibcp.jar

  3. In addition, you might have to set the following in your server.policy file.

    For more information about the server.policy file, see The server.policy File 

    grant codeBase "file:Optimizeit-dir/lib/optit.jar" {
	permission java.security.AllPermission;
};

  4. Restart the Application Server.

    When the server starts up with this configuration, you can attach the profiler.

See Also

For further details, see the Optimizeit documentation.

Troubleshooting

If any of the configuration options are missing or incorrect, the profiler might experience problems that affect the performance of the Application Server.