Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide

Node Agent and Domain Administration Server Synchronization

Because configuration data is stored in the Domain Administration Server’s repository (the central repository) and also cached on the node agent’s local machine, the two must be synchronized. The synchronization of cache is always done on a explicit user action through the administration tools.

This section contains the following topics:

Node Agent Synchronization

When a node agent is started for the first time, it sends a request to the Domain Administration Server (DAS) for the latest information in the central repository. Once it successfully contacts the DAS and gets configuration information, the node agent is bound to that DAS.


Note –

By default, the asadmin start-node-agent command automatically starts the remote server instances without synchronizing with DAS. If you are starting a remote server instance that is synchronized with the central repository managed by DAS, specify the --startinstances=false option of the asadmin start-node-agent command. Then use the asadmin start-instance command to start the remote server instance.


If you created a placeholder node agent on the DAS, when the node agent is started for the first time it gets its configuration from the central repository of the DAS. During its initial start-up, if the node agent is unable to reach the DAS because the DAS is not running, the node agent stops and remains unbound.

If changes are made in the domain to the node agent’s configuration, they are automatically communicated to the node agent on the local machine while the node agent is running.

If you delete a node agent configuration on the DAS, the next time the node agent synchronizes, it stops and marks itself as awaiting deletion. Manually delete it using the local asadmin delete-node-agent command.

Server Instance Synchronization

If you explicitly start a server instance with the Admin Console or asadmin tool, the server instance is synchronized with the central repository. If this synchronization fails, the server instance doesn’t start.

If a node agent starts a server instance without an explicit request through the Admin Console or the asadmin tool, the repository cache for the server instance is not synchronized. The server instance runs with the configuration as stored in its cache. You must not add or remove files in the remote server instance's cache.

The remote server instance's configuration are treated as cache (all files under nodeagents/na1/server1) and owned by Application Server. In extreme cases, if user removes all files of a remote server instance and restarts the node agent, the remote server instance (for example, server1) will be recreated and all necessary files will be synchronized.

The following files and directories are kept synchronized by the Application Server.

Table 7–1 Files and directories synchronized among remote server instances

File or directory 

Description 

applications

All deployed applications. The parts of this directory (and sub directories) synchronized depend on the applications referred to from the server instance. The Node agent does not synchronize any of the applications because it does not reference any application. 

config

Contains configuration files for the entire domain. All the files in this directory are synchronized except runtime temporary files, such as, admch, admsn, secure.seed, . timestamp, and __timer_service_shutdown__.dat.

config/config_name

Directory to store files to be shared by all instances using config named config_name. There will be one such directory for every config defined in domain.xml. All the files in this directory are synchronized to the server instances that are using the config_name.

config/config_name/lib/ext

Folder where Java extension classes (as zip or jar archives) can be dropped. This is used by applications deployed to server instances using config named config_name. These jar files are loaded using Java extension mechanism.

docroot 

The HTTP document root. In out of the box configuration, all server instances in the domain use the same docroot. The docroot property of the virtual server needs to be configured to make the server instances use a different docroot. 

generated 

Generated files for Java EE applications and modules, for example, EJB stubs, compiled JSP classes, and security policy files. This directory is synchronized along with applications directory. Therefore, only the directories corresponding to applications referenced by a server instance are synchronized. 

lib, lib/classes 

Folder where common Java class files or jar and zip archives used by applications deployed to entire domain can be dropped. These classes are loaded using Application Server's class loader. The load order in class loader is: lib/classes, lib/*.jar, lib/*.zip.

lib/ext 

Folder where Java extension classes (as zip or jar archives) used by applications deployed to entire domain can be dropped. These jar files are loaded using Java extension mechanism. 

Synchronizing Library Files

The --libraries deploy time attribute for an application can be used to specify runtime dependencies of an application.

To make a library available to the whole domain, you could place the JAR file in domain-dir/lib or domain-dir/lib/classes. (For more information, see Using the Common Classloader in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Developer’s Guide. ) This is usually the case for JDBC drivers and other utility libraries that are shared by all applications in the domain.

For cluster-wide or stand alone server wide use, copy the jars into the domain-dir/domain1/config/xyz-config/lib directory. Next, add the jars in classpath-suffix or classpath-prefix element of xyz-config. This will synchronize the jars for all server instances using xyz-config.

In summary:

Unique Settings and Configuration Management

Configuration files (under domains/domain1/config are synchronized across the domain. If you want to customize a server.policy file for a server1-config used by a stand alone server instance (server1), place the modified server.policy file under domains/domain1/config/server1-config directory.

This modified server.policy file will only be synchronized for the stand alone server instance, server1. You should remember to update the jvm-option. For example: <java-config> ...<jvm-options>-Djava.security.policy=${com.sun.aas.instanceRoot}/config/server1-config/server.policy</jvm-options></java-config>

Synchronizing Large Applications

When your environment contains large applications to synchronize or available memory is constrained, you can adjust the JVM options to limit memory usage. This adjustment reduces the possibility of receiving out of memory errors. The instance synchronization JVM uses default settings, but you can configure JVM options to change them.

Set the JVM options using the INSTANCE-SYNC-JVM-OPTIONS property. The command to set the property is:

asadmin set 
domain.node-agent.node_agent_name.property.INSTANCE-SYNC-JVM-OPTIONS="JVM_options"

For example:

asadmin set 
domain.node-agent.node0.property.INSTANCE-SYNC-JVM-OPTIONS="-Xmx32m -Xss2m"

In this example, the node agent is node0 and the JVM options are -Xmx32m -Xss2m.

For more information, see http://java.sun.com/docs/hotspot/VMOptions.html.


Note –

Restart the node agent after changing the INSTANCE-SYNC-JVM-OPTIONS property, because the node agent is not automatically synchronized when a property is added or changed in its configuration.


Using the doNotRemoveList Flag

If your application requires to store and read files in the directories (applications, generated, docroot, config, lib) that are synchronized by the Application Server, use the doNotRemoveList flag. This attribute takes a coma-separated list of files or directories. Your application dependent files are not removed during server startup, even if they do not exist in the central repository managed by DAS. If the same file exists in the central repository, they will be over written during synchronization.

Use the INSTANCE-SYNC-JVM-OPTIONS property to pass in the doNotRemoveList attribute.

For example:

<node-agent name="na1" ...>

...

<property name="INSTANCE-SYNC-JVM-OPTIONS" value="-Dcom.sun.appserv.doNotRemoveList=applications/j2ee-modules/<webapp_context>/logs,generated/mylogdir"/>

</node–agent>