Sun Java System Web Server 7.0 Update 1 Administrator's Guide

Chapter 11 Working With Java and Web Applications

This chapter describes the procedures for editing Java settings for a virtual server. You can edit Java settings from the administration console or the wadm command line tool. This chapter also describes various Java resources that can be configured in the server.

This chapter also describes how Java web applications can be deployed in the server.

Configure Java to Work With Sun Java System Web Server

This section lets you enable Java and set Java Home variable for the selected configuration.

ProcedureEnabling Java for Your Configuration

  1. Select the Configuration.

    Select the configuration from the configuration list. Click Configuration tab to get the list of available configurations.

  2. Click on Java > General tab.

  3. Click Enable Java check box.

    Turn on/off Java support for the configuration. Enabling Java allows the server to process Java applications.

  4. Set Java Home.

    Specify the location of the Java SE. Specify the absolute path or path relative to the server's config directory.

  5. Set Stick Attach.

    Specify whether the server attaches each HTTP request processing thread to the JVM only once (Otherwise the server attaches/detaches the HTTP request processing thread on each request).


    Note –

    Using CLI

    For enabling Java for a configuration, execute the following command.


    wadm> enable-java --user=admin --password-file=admin.pwd --host=serverhost 
    --port=8989 --config=config1

    See CLI Reference, enable-java(1).


Setting Up Java Class Path

This section lets you add JVM class path for the selected configuration.

ProcedureTo Set Up Java Class Path

  1. Select the Configuration.

    Select the configuration from the configuration list. Click Configuration tab to get the list of available configurations.

  2. Click on Java > Path Settings tab.

    Edit the following parameters:

    • Ignore Environment Class Path — Enabled by default.

    • Class Path Prefix — Prefix for the system class path. You should only prefix the system class path if you wish to override system classes, such as the XML parser classes. Use this with caution.

    • Server Class Path — Class path containing server classes. Read-Only list.

    • Class Path Suffix — Append to server class path.

    • Native Library Path Prefix — Prefix for the operating system native library path.

    • Bytecode Preprocessor Class — Fully qualified name of a class that implements com.sun.appserv.BytecodePreprocessor. A typical way to perform runtime class instrumentation is through the preprocessing mechanism, whereby profiling and monitoring tools use a class preprocessor to insert instrumentation code at the required places in the Java classes just before they are loaded by the JVM. Toward that end, the class preprocessor works in conjunction with the class loader.

Configuring Your JVM

To set JVM command-line options in the Administration interface, perform the following tasks:

ProcedureTo Configure Your JVM

  1. Select the Configuration.

    Select the configuration from the configuration list. Click Configuration tab to get a list.

  2. Click on Java > JVM Settings tab.

    Configure the settings for your JVM.

Adding a JVM Option

You can add/delete command line JVM options by specifying the values here.

Click Add JVM Option button to add a JVM option.

Some examples for JVM options are:-Djava.security.auth.login.config=login.conf, -Djava.util.logging.manager=com.iplanet.ias.server.logging.ServerLogManager and -Xms128m -Xmx256m


Note –

Using CLI

For adding JVM options through CLI, execute the following command.


wadm> create-jvm-options --user=admin --password-file=admin.pwd --host=serverhost 
--port=8989 --config=config1 -Dhttp.proxyHost=proxyhost.com -Dhttp.proxyPort=8080

See CLI Reference, create-jvm-options(1).


Adding JVM Profilers

JVM Profiler helps you diagnose and resolve performance problems, memory leaks, multi-threading problems and system resource usage problems in your Java applications to ensure the highest level of stability and scalability for your applications.

ProcedureTo Add a JVM Profiler

  1. Select the Configuration.

    Select the configuration from the configuration list. Click Configurations tab to get the list of available configuration.

  2. Click Java > JVM Settings tab.

  3. Click New button under Profilers section.

  4. Provide values for the following parameters:

    • Name — Provide a short name for the new JVM Profiler.

    • Enabled — Determines if the profiler is enabled at runtime.

    • Class path — Provide a valid class path for the profiler. (Optional).

    • Native library path — Provide a valid native library path. (Optional).

    • JVM Options — You can specify additional JVM options for the CLI.


    Note –

    Using CLI

    For adding a JVM profiler through CLI, execute the following command.


    wadm> create-jvm-profiler --user=admin --password-file=admin.pwd 
    --host=serverhost --port=8989 --config=config1

    See CLI Reference, create-jvm-profiler(1).


Enabling Java Debugging for Your Server

The JVM can be started in debug mode and can be attached with a JPDA (Java Platform Debugger Architecture) debugger. When you enable debugging, you enable both local and remote debugging.

Sun Java System Web Server's debugging is based on the JPDA software. To enable debugging, perform the following tasks.

ProcedureEnable JVM Debugging

  1. Select the Configuration.

    Select the configuration from the configuration list. Click Configurations tab to get the list of available configuration.

  2. Click Java > JVM Settings tab.

  3. Select Enable Debug checkbox under Debug Java Settings.

  4. Provide JVM options as necessary by clicking the New button.

    The default JPDA options are as follows:


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

    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 the port to use when attaching the JVM to a debugger, specify address=port_number. Check out the JPDA documentation for a list of debugging options.

Deploying Java Web Applications

Adding a Web Application

You can deploy a web application to any existing virtual server.

ProcedureTo deploy a web application

Before You Begin
Sun Java System Web Server 7.0 Update 1

Web applications can be deployed through wadm, Administration Console and other supported IDEs.

  1. Click on the Virtual Servers tab under a Server Configuration, for deploying a web application.

  2. Select the virtual server, in which you will need to deploy the web application.

  3. Click on the Web Applications tab > New button.

  4. Specify the web application package.

    If you need to upload a web application archive, click on the Browse button and select the archive. Optionally, you can also specify a web application archive located in the server.

  5. Specify the URI for your web application. This will be the applications context root and is relative to the server host.

  6. Provide a short description about the web application.

  7. Enable/Disable JSP Pre-compilation.

    Enabling this directive will allow all the JSPs present in the web application to be pre-compiled to improve performance.

  8. Enable the application.

    When a web application state is set to be Disabled, it will not be available on request. However you can toggle this option anytime without redeploying the application to the instances.

  9. Deploy the application.

    Click on the Deploy button to deploy the web application.

    You can access the application with the context root specified. E.g. http://<your-server>:<port>/<URI>


    Note –

    Using CLI


    wadm> add-webapp --user=admin --password-file=admin.passwd --host=localhost 
     --port=8888 --config=config1 --vs=HOSTNAME --uri=/hello /home/test/hello.war

    See CLI Reference, add-webapp(1).


Deploying a Web Application Directory

Directory on the administration server host machine can be deployed to a configuration using the –file-on-server option. Execute the following command:


wadm> add-webapp --user=admin-user --password-file=admin.passwd 
--port=8989 --vs=vs1 --config=config1 --file-on-server
--uri=/mywebapp /space/tmp/mywebapp

Pre-compiling JSPs During Deployment

For pre-compiling JSPs in a web application while deploying the web application, execute the command with –precompilejsp option as given below:


wadm> add-webapp --user=admin-user --password-file=admin.passwd 
--port=8989 --vs=vs1 --config=config1 --file-on-server --uri=/mywebapp
--precompilejsp mywebapp.war

Configuring Your Servlet Container

This section describes the procedure for configuring the servlet container.

ProcedureTo Set Up Servlet Container

  1. Select the configuration.

    Select the configuration from the configuration list. Click Configurations tab to get the list.

  2. Click on Java > Servlet Container.

Servlet Container Global Parameters

The following table describes the parameters available on the servlet container page.

Table 11–1 Servlet Container Parameters

Parameter

Description

Log Level

Log verbosity for the servlet container. The values can be finest (most verbose), finer, fine, info, warning, failure, config, security, or catastrophe (least verbose). 

Dynamic Reload Interval

This parameter defines the time period after which the server checks deployed web applications for modifications. The value range is 1 to 60, or –1 if dynamic reloading should be disabled. 

Anonymous Role

Name of the default, or anonymous, role assigned to all principals. The default role is ANYONE. 

Servlet Pool Size

Number of servlet instances to instantiate per SingleThreadedServlet. The range value is 1 to 4096.

Dispatcher Max Depth

Maximum depth for the servlet container allowing nested request dispatches. The range of values can be between 0 and 2147.0483647.0. The default value is 20. 

Allow Cross Context

Whether request dispatchers are allowed to dispatch to another context. The default value is false. 

Encode Cookies

Whether the servlet container encodes cookie values. The default value is true. 

Reuse Session IDs

Whether any existing session ID number is reused when creating a new session for that client. The default value is false. 

Secure Session Cookie

Dynamic/True/False. This parameter controls under what conditions the JSESSIONID cookie is marked secure. Use dynamic (default) to mark the cookie secure only when the request was received on a secure connection (HTTPS). 

Select True to always mark it secure and false to never mark it secure. 

Configuring Server Lifecycle Modules

Java Server Lifecycle Modules are Java classes that listen for server lifecycle events in order to perform certain tasks whenever server events like start or stop occur.

The server supports running short or long duration Java based tasks within the web server environment. These tasks get automatically initiated upon server startup and be notified upon server shutdown. So now you can hook up tasks like instantiating singletons and RMI servers.

A brief description of the Server's lifecycle is given below.

Introduction to Server Lifecycle

ProcedureTo Add a Lifecycle Module

  1. Select the Configuration.

    Select the configuration, from the configuration list. For viewing the list of configuration, click Configuration tab.

  2. Click Java > Lifecycle Modules tab.

  3. Click New button.

    Provide values for the following parameters:

    • Name — Provide a valid unique name for the new lifecycle module.

    • Enabled — If you want to enable this lifecycle module, use this option.

    • Class Name — Fully qualified Java class name. The class should implement com.sun.appserv.server.LifecycleListener interface. For more information on using this interface, refer to the Developer's Guide.

    • Class Path — Optional. You can specify a class path to the listener class.

    • Load Order — Greater than 100. Order of loading the lifecycle event listeners, in the numerical order. It is recommended to choose a load-order that is greater than or equal to 100 to avoid conflicts with internal lifecycle modules.

    • On Load Failure — If this option is enabled, the server does not treat exceptions thrown from the listener classes as fatal thus it continues with the normal startup. Disabled by default.

    • Description — Provide a short description about the lifecycle module.

    • Properties — Properties can be used to pass arguments to a Java Lifecycle Module. For adding a new property, click Add Property button and enter text for name, value and description.


    Caution – Caution –

    The server lifecycle listener classes are invoked synchronously from the main server thread and hence extra precaution must be taken to ensure that the listener classes do not block the server. The listener classes may create threads if appropriate but they must be stopped during the shutdown/termination phases.


ProcedureTo Delete a Lifecycle Module

  1. Select the Configuration.

    Select the configuration, from the configuration list. For viewing the list of configuration, click Configuration tab.

  2. Click Java > Lifecycle Modules tab.

  3. Select the lifecycle module and click Delete Lifecycle Module button.


    Note –

    Using CLI

    The following example depicts how to create a Java Lifecycle Module named myLifecycleModule for the configuration test, implemented by the class com.MyLifecycleModule.


    wadm> create-lifecycle-module --user=admin --password-file=admin.pwd 
    --host=serverhost --port=8989 --config=config1 
    --class=com.sun.webserver.tests.LifecycleClass LifecycleTest

    See CLI Reference, create-lifecycle-module(1).

    For listing Java Lifecycle Modules execute the following command:


    wadm> list-lifecycle-modules --config=test

    See CLI Reference, list-lifecycle-modules(1).

    For adding properties to Java Lifecycle Modules, execute the following command:


    wadm> create-lifecycle-module-userprop --user=admin --password-file=admin.pwd 
    --host=serverhost --port=8989 --config=config1 --module=LifecycleTest info=Testing

    See CLI Reference, create-lifecycle-module-userprop(1).

    For modifying Java Lifecycle Module properties, execute the following command:


    wadm> set-lifecycle-module-prop --user=admin --password-file=admin.pwd 
    --host=serverhost --port=8989 --config=config1 --module=LifecycleTest 
    class-path=/space 

    See CLI Reference, set-lifecycle-module-prop(1)


Configuring Java Resources

Web applications may access a wide variety of resources such as resource managers, data sources (for example SQL datasources), mail sessions, and URL connection factories. The Java EE platform exposes such resources to the applications via Java Naming and Directory Interface (JNDI) service.

Sun Java System Web Server allows you to create and manage the following Java EE resources:

Configuring JDBC Resources

A JDBC Datasource is a Java EE resource that you can create and manage using Sun Java System Web Server.

The JDBC API is the API for connectivity with relational database systems. The JDBC API has two parts:

A JDBC Datasource object is an implementation of a data source in the Java programming language. In basic terms, a data source is a facility for storing data. It can be as sophisticated as a complex database for a large corporation or as simple as a file with rows and columns. A JDBC datasource is a Java EE resource that can be created and managed via Sun Java System Web Server.

The JDBC API provides a set of classes for Java with a standard SQL database access interface to ensure uniform access to a wide range of relational databases.

Using JDBC, SQL statements can be sent to virtually any database management system (DBMS). It is used as an interface for both relational and object DBMSs.

Adding a JDBC Resource

For adding a JDBC resource through CLI, execute the following command.


wadm> create-jdbc-resource --user=admin --password-file=admin.pwd --host=serverhost
--port=8989 --config=config1 --datasource-class=oracle.jdbc.pool.OracleDataSource jdbc

See CLI Reference, create-jdbc-resource(1).

In the above example, com.pointbase.jdbc.jdbcDataSource represents the JDBC driver class.

For a list of supported JDBC drivers, see JDBC Drivers Known to Work With Sun Java System Web Server.

JDBC Drivers Known to Work With Sun Java System Web Server

The following table provides a list of common JDBC drivers and their properties that needs to be configured while adding a new JDBC resource. See Adding a new JDBC Resource.

Table 11–2 List of common and JDBC drivers

Driver

Class Name

Properties

Oracle driver

oracle.jdbc.pool.OracleDataSource

  • url

  • user

  • password

Sun Java System JDBC driver for Oracle

com.sun.sql.jdbcx.oracle.OracleDataSource

  • serverName

  • portNumber

  • user

  • password

  • SID

DB2 IBM driver

com.ibm.db2.jdbc.DB2DataSource

  • serverName

  • databaseName

  • portNumber

  • user

  • password

  • driverType

Sun Java System JDBC driver for DB2

com.sun.sql.jdbcx.db2.DB2DataSource

  • databaseName

  • locationName

  • packageName

  • password

  • portNumber

  • serverName

  • user

MS SQLServer driver

com.ddtek.jdbcx.sqlserver.SQLServerDataSource

  • databaseName

  • password

  • user

  • serverName

  • portNumber

Sun Java System JDBC driver for MS

com.sun.sql.jdbcx.sqlserver.SQLServerDataSource

  • databaseName

  • password

  • user

  • serverName

  • portNumber

Sybase driver

com.sybase.jdbcx.SybDataSource

  • databaseName

  • password

  • portNumber

  • serverName

  • user

Sun Java System JDBC driver for Sybase

com.sun.sql.jdbcx.sybase.SybaseDataSource

  • databaseName

  • password

  • user

  • portNumber

  • serverName

MySQL driver

com.mysql.jdbc.jdbc2.optional.MysqlDataSource

  • serverName

  • port

  • databaseName

  • user

  • password

Informix driver

com.informix.jdbcx.IfxDataSource

  • portNumber

  • databaseName

  • IfxIFXHOST (The IP address or the host name of the computer running the Informix database)

  • serverName

  • user

  • password

Sun Java System JDBC driver for Informix

com.sun.sql.jdbcx.informix.InformixDataSource

  • databaseName

  • informixServer ( The name of the Informix database server to which you want to connect)

  • password

  • portNumber

  • severName

PostgreSQL driver

org.postgresql.ds.PGSimpleDataSource

  • serverName

  • databaseName

  • portNumber

  • user

  • password

Apache Derby driver

org.apache.derby.jdbc.EmbeddedDataSource

  • databaseName

  • user

  • password


Note –

In the above mentioned list, all of the Sun Java System JDBC drivers are shipped with the Web Server. For other drivers, check with the driver vendor documentation for the latest versions of these drivers and the class names. The information provided in the above list may not be the latest driver information.


Managing JDBC Resources

ProcedureAdding a new JDBC Resource

  1. Select the configuration.

    Select the configuration from the configuration list. Click Configurations tab to get the list.

  2. Click on Java > Resources tab.

  3. Click on New button under JDBC Resources section.

  4. Select the Driver Vendor.

    Specify a unique value for the JNDI name and select the JDBC driver vendor from the available list.

  5. Provide JDBC Resource Properties.

    Based on the JDBC driver vendor selection in the previous step, the class name for the driver and the JDBC resource properties are automatically populated.

  6. Review.

    View the summary and click on Finish to create the new JDBC resource.

Managing JDBC Connection Pools

Configuring JDBC Connection Pool

In Sun Java System Web Server 7.0 Update 1, JDBC Connection Pools are configured through jdbc-resource elements. The simplest connection pool can be configured by following the steps listed below. In this example, the connection pool will use the Oracle JDBC driver.

ProcedureTo Create a JDBC Connection Pool

  1. Start wadm.

  2. Create JDBC Resource.

    Create a JDBC resource with the basic configuration. Other attributes are available to fine tune the connection pool. Refer the Man Pages for more attributes and examples.


    wadm> create-jdbc-resource --config=test 
    --datasourceclass=oracle.jdbc.pool.OracleDataSource jdbc/MyPool
  3. Configure Vendor Specific Properties.

    Properties are used to configure the driver's vendor specific properties. In the example below the properties url, user and password are added to the JDBC resource.


    wadm> add-jdbc-resource-userprop --config=test --jndi-name=jdbc/MyPool 
    url=jdbc:oracle:thin:@hostname:1521:MYSID user=myuser password=mypassword
  4. Enable Connection Validation.

    Connection validation can be enabled for the pool. If this option is used, connections will be validated before they are passed to the application. This allows the web server to automatically re-establish database connections in the case of the database becoming unavailable due to network failure or database server crash. Validation of connections will incur additional overhead and slightly reduce performance.


    wadm> set-jdbc-resource-prop --config=test --jndi-name=jdbc/MyPool 
    connection-validation-table-name=test connection-validation=table
  5. Change Default Pool Settings.

    In this example, let us change the maximum number of connections.


    wadm> set-jdbc-resource-prop --config=test --jndi-name=jdbc/MyPool 
    max-connections=100
  6. Deploy the Configuration.


    wadm> deploy-config test
  7. Provide the Jar Files Containing the JDBC driver.

    The server needs to be provided with the classes that implement the driver. This can be done in two ways:

    • Copy the driver's jar file into the server instance lib directory. This is the simplest way, as the jar files included in the instance lib directory will be automatically loaded and available to the server.

    • Modify the JVM's class-path-suffix to include the JDBC driver's jar file.


      wadm> set-jvm-prop  --config=test class-path-suffix=/export/home/lib/classes12.jar
  8. Usage in Web Applications.

    • Modifying WEB-INF/web.xml.


      <web-app>
      ...
        <resource-ref>
          <description>JDBC Connection Pool</description>
          <res-ref-name>jdbc/myJdbc</res-ref-name>
          <res-type>javax.sql.DataSource</res-type>
          <res-auth>Container</res-auth>
        </resource-ref>
      ...
      </web-app>
    • Modifying WEB-INF/sun-web.xml.


      <sun-web-app>
      ...
        <resource-ref>
          <res-ref-name>jdbc/myJdbc</res-ref-name>
          <jndi-name>jdbc/MyPool</jndi-name>
        </resource-ref>
      ...
      </sun-web-app>
    • Using the Connection Pool.


      Context initContext = new InitialContext();
          Context webContext = (Context)context.lookup("java:/comp/env");
      
          DataSource ds = (DataSource) webContext.lookup("jdbc/myJdbc");
          Connection dbCon = ds.getConnection();

Registering Custom Resources

You can register a custom resource with the instance by following this task.

ProcedureTo Add a Custom Resource

  1. Select the configuration.

    Select the configuration from the configuration list. Click Configurations tab to get the list.

  2. Click on Java > Resources tab.

  3. Click New button under Custom Resource section.

Properties for Custom Resources

The following table describes the properties available for creating a custom resource.

Table 11–3 Custom Resources Properties

Property

Description

JNDI Name

Provide a unique JNDI name for the custom resource. 

Enabled

Determines if this custom resource is enabled at runtime. 

Resource Type

Fully qualified type of this resource. 

Factory Class

Class that instantiates resources of this type. The fully qualified name of the user-written factory class that implements javax.naming.spi.ObjectFactory.

Description

Provide a short description for the custom resource. 

Properties

Optionally provide CLI properties by clicking Add Property button. 


Note –

Using CLI

For creating a custom resource through CLI, execute the following command:


wadm> create-custom-resource --user=admin --password-file=admin.pwd --host=serverhost 
--port=8989 --config=config1 --res-type=samples.jndi.customResource.MyBean 
--factory-class=samples.jndi.customResource.MyCustomConnectionFactory custom

See CLI Reference, create-custom-resource(1).


Working With External JNDI Resources

Creating External JNDI Resources

This option lets you create an external Java Naming and Directory Interface (JNDI) resource. You need aNDI resource to access resources stored in an external JNDI repository.

ProcedureTo Add an External JNDI Resource

  1. Select the configuration.

    Select the configuration from the configuration list. Click Configurations tab to get the list.

  2. Click on Java > Resources tab.

  3. Click New button under External JNDI section.

Properties for External JNDI Resources

The following table describes the properties available while adding a new external JNDI resource.

Table 11–4 External JNDI Resources Properties

Property

Description

JNDI Name

Provide a unique name for the new external JNDI resource. 

Enabled

Determines if this external JNDI resource is enabled at runtime. 

External JNDI Name

Name of the external JNDI resource. 

Resource Type

Fully qualified type of this resource. 

Factory Class

Class that instantiates resources of this type. 

Description

Provide a short description for the external JNDI resource. 

Properties

Optionally provide CLI properties by clicking Add Property button. 


Note –

Using CLI

For creating an external JNDI resource through CLI, execute the following command:


wadm> create-external-jndi-resource --user=admin 
--password-file=admin.pwd --host=serverhost --port=8989 --config=config1 
--res-type=org.apache.naming.resources.Resource 
--factory-class=samples.jndi.externalResource.MyExternalConnectionFactory 
--jndilookupname=index.html external-jndi

See CLI Reference, create-external-jndi-resource(1).


Configuring Mail Resources

JMS destinations are Java EE resources that can be created and managed via Sun Java System Web Server.

Many internet applications require the ability to send email notifications, so the Java EE platform includes the JavaMail API along with a JavaMail service provider that allows an application component to send internet mail.

ProcedureTo Add a Mail Resource

  1. Select the Configuration.

    Select the configuration from the configuration list. Click Configurations tab to get the list.

  2. Click on Java > Resources tab.

  3. Click on New button under Mail Resource section.

Properties for Mail Resource

The following table describes the properties available while adding a new mail resource.

Table 11–5 Mail Resource Properties

Property

Description

JNDI Name

Provide a unique name for the new mail resource. 

Enabled

Determines if this mail resource is enabled at runtime. 

User

Valid user name registered in the mail server. 

From

Email address from which the server sends mail. 

Host

Host name/IP address of the mail server. 

Store Protocol

Protocol used to retrieve messages. 

Store Protocol Class

Storage service provider implementation for store-protocol. Fully qualified class name of a class that implements store-protocol. The default class is com.sun.mail.imap.IMAPStore.

Transport Protocol

Protocol used to send messages. 

Transport Protocol Class

Transport service provider implementation for transport-protocol. Fully qualified class name of a class that implements transport-protocol. The default class is com.sun.mail.smtp.SMTPTransport.


Note –

Using CLI

For creating a mail resource, execute the following command:


wadm> create-mail-resource --config=test --server-host=localhost 
--mail-user=nobody --from=xyz@foo.com mail/Session

See CLI Reference, create-mail-resource(1).


Configuring SOAP Authentication Providers

Java Authentication Service Provider Interface for Containers specification defines a standard service provider interface by which authentication mechanism providers may be integrated with containers. You can use the Administration Console to add a new SOAP authentication provider.

ProcedureTo Add a SOAP Authentication Provider

  1. Select the configuration.

    Select the configuration from the configuration list. Click Configurations tab to get the list.

  2. Click on Java > Web Services tab.

  3. Click on New button under SOAP Authentication Provider section.

SOAP Authentication Provider Parameters

The following table describes the parameters available on the new SOAP authentication provider page.

Table 11–6 SOAP Authentication Provider Parameters

Parameter

Description

Name

Enter a short name for the new SOAP authentication provider. 

Class Name

The class that implements the provider. Fully qualified class name of a class that implements javax.security.auth.XXX

Request Authentication Source

This attribute defines a requirement for message layer sender authentication such as username/password or content authentication such as digital signature to be applied to request messages. The value (auth-policy) may be sender or content. When this argument is not specified, source authentication of the request is not required. 

Request Authentication Recipient

This attribute defines a requirement for message layer authentication of the receiver of a message to its sender, for example, by XML encryption. The values can be before-content or after-content. 

Response Authentication Source

This attribute defines a requirement for message layer sender authentication such as username/password or content authentication such as digital signature to be applied to response messages. The value (auth-policy) may be sender or content. When this argument is not specified, source authentication of the response is not required 

Response Authentication Recipient

This attribute defines a requirement for message layer authentication of the receiver of the response message to its sender, for example, by XML encryption. 

Properties

Provide other CLI properties by clicking Add Property button. 


Note –

Using CLI

For adding a SOAP authentication provider using CLI, execute the following command.


wadm> create-soap-auth-provider --user=admin --password-file=admin.pwd 
--host=serverhost --port=8989 --config=config1 
--class-name=javax.security.auth.soapauthprovider soap-auth

See CLI Reference, create-soap-auth-provider(1).


Configuring Session Replication

Sun Java System Web Server 7.0 update 1 supports session replication that provides high availability to web applications. Session replication achieves this by replicating HTTP sessions from one instance to another server instance of the same cluster. So, each HTTP session has a backup copy on a remote instance. In the event of a failure which renders one instance in the cluster unavailable, the cluster still maintains session continuity.

Sun Java System Web Server 7.0 Update1Sun Java System Web Server 7.0 Update 1

The above figures depicts a typical scenario when session replication happens between four nodes with a reverse proxy set up. Note that the session data gets replicated from Web Server B to Web Server D when Web Server C goes offline.

Setting Up Session Replication

This section describes the procedure for setting up session replication properties for a selected configuration.

ProcedureTo Set Up Session Replication

  1. Select the configuration.

    Select the configuration from the configuration list. Click Configurations tab to get the list.

  2. Click on Java > Session Replication.

Modifying Session Replication Parameters

The following table describes the parameters available on the session replication page.

Table 11–7 Session Replication Parameters

Parameter

Description

Port

Port number where the Administration server is listening. The default port is 8888. 

Enabled

Enable session replication for the selected configuration. 

Encrypted

Whether session data is encrypted prior to replication. The default value is false. 

Cipher

The cipher suite (algorithm, mode, padding) the cluster members uses to replicate session data. 

Getatrribute triggers replication

Whether a call to the HttpSession.getAttribute method should cause a session to be backed up. The default value is true.

Replica discover max hops

Maximum number of instances that should be contacted while attempting to find the backup of a session. The range of value is 1 to 2147.0483647.0, or -1 for no limit. 

Startup discover timeout

Maximum time (in seconds) that an instance will spend trying to contact its designated backup instance. The range of value is 0.001 to 3600. 

Cookie name

Enter the name of the cookie that tracks which instance owns a session. 

Managing Authentication Realms

The Java EE based security model provides for security realms that identify and authenticate users.

The authentication process verifies users through a Java realm. A realm consists of a set of users, optional group mappings, and authentication logic that can validate authentication requests. Once an authentication request is validated by a configured realm and the security context established, this identity is applied to all subsequent authorization decisions.


Note –

The Java realms are analogous to the auth-dbs (Authentication Databases) with the difference that while auth-dbs are used by the ACL engine (based on rules in your ACL file), the Java Realms are used by the Java Servlet access control rules (specified in each web application's web.xml file).


A server instance may have any number of configured realms. The configuration information is present in the auth-realm element in the server.xml file.

The following table defines the different types of realms supported in Sun Java System Web Server 7.0 Update 1

Table 11–8 Types of Realms

Realm

Description

File

The file realm is the default realm when you first install the Sun Java System Web Server. This realm, easy and simple to set up, represents a significant convenience to developers.

The file realm authenticates users against user data stored in a text file. The Java Realms are analogous to the auth-dbs (Authentication Databases) with the difference that while auth-dbs are used by the ACL engine (based on rules in your ACL file), the Java Realms are used by the Java Servlet access control rules (specificed in each web application's web.xml).

LDAP

The ldap realm allows you to use an LDAP database for user security information. An LDAP directory service is a collection of attributes with unique identifiers. The ldap realm is ideal for deployment to production systems.

In order to authenticate users against the ldap realm, you must create the desired user(s) in your LDAP directory. You can do this from the Administration Server’s Users & Groups tab. You can also perform this action from your LDAP directory product’s user management console.

PAM

The PAM (aka Solaris) realm delegates authentication to the Solaris PAM stack. As with the PAM auth-db, this realm is only supported on Solaris 9 and 10 and the server instance must be running as root.  

Certificate

The certificate realm supports SSL authentication. The certificate realm sets up the user identity in the Sun Java System Web Server’s security context and populates it with user data from the client certificate. The Java EE containers then handle authorization processing based on each user’s DN from his or her certificate. This realm authenticates users with SSL or TLS client authentication through X.509 certificates.

Native

The native realm is a special realm that provides a bridge between the core ACL-based authentication model and the Java EE/Servlet authentication model. By using the Native realm for Java web applications it becomes possible to have the ACL subsystem perform the authentication (instead of having the Java web container do so) and yet have this identity available for Java web applications.

When an authentication operation is invoked, the Native realm delegates this authentication to the core authentication subsystem. From the user’s perspective this is essentially equivalent to, for example, the LDAP realm delegating authentication to the configured LDAP server. When group membership queries are processed by the Native realm, they are also delegated to the core authentication subsystem. From the Java web modules and the developers perspective, the Native realm is no different from any of the other Java realms which are available for use with web modules. 

Custom

You can build realms for other databases, such as Oracle, to suit your specific needs by using pluggable JAAS login modules and a realm implementation. 

The following section describes the steps involved in adding a new authentication realm.

ProcedureTo Add a Authentication Realm

  1. Select the configuration.

    Select the configuration for which you need to add a new authentication realm. Click Configurations tab and select the configuration.

  2. Click on Java > Security tab.

  3. Click New Authentication Button.

  4. Provide Realm Details.

    • Name — Enter a short name for the realm. This name is used to refer to the realm from, for example, web.xml.

    • Class — If you are configuring a custom realm, enter the full Java class name which implements your custom realm. There is no need to enter a class for any of the built-in realms.

    • Type — Select the type of realm. See previous section where Java Realm types are discussed.

    • Properties — Add realm specific properties. For instance property name="file" value="instance_dir/config/keyfile" and property name="jaas-context" value="fileRealm.


    Note –

    Using CLI

    For adding an authentication realm through CLI, execute the following command.


    wadm> create-auth-realm --user=admin --password-file=admin.pwd --host=serverhost 
    --port=8989 --config=config1 basic

    See CLI Reference, create-auth-realm(1).

    Specify the name of a built-in authentication realm type. The type can be file, ldap, pam, native or certificate.