Chapter 3 Application Client Deployment Descriptors

This chapter describes the application client deployment descriptors. This chapter contains the following topics:

Introducing Application Client Deployment Descriptors

Deployment descriptors are the XML files used to configure the runtime properties of a module or application. The J2EE Specification defines the format of these descriptors. You can view and edit the deployment descriptors using a text editor at any time during the development process.

Sun Java System Application Server application clients require three deployment descriptors files:

Format of Deployment Descriptors

A deployment descriptor file defines the elements that an XML file can contain and the subelements and attributes these elements can have. The sun-application-client-1_3-0.dtd file defines the format of the sun-application-client.xml file. The sun-application-client-container-1_0.dtd file defines the format of sun-acc.xml file. These DTD files are located in the install_dir/lib/dtds directory.

Each element defined in a DTD file (which may be present in the corresponding XML file) can contain the following:

Subelements


Note	Do not edit the DTD files. Their contents change only with new versions of Sun Java System Application Server.

An element can contain other elements. For example, the following code defines the client-container element.

<!ELEMENT client-container(target-server,auth-realm?,client-credential?, log-service?,property*))>

The ELEMENT tag specifies that a client-container element can contain target-server, auth-realm, client-credential, log-service, property subelements.

The following table shows how optional suffix characters of subelements determine the requirement rules, or number of allowed occurrences, for the subelements. The left column lists the subelement ending character, and the right column lists the corresponding requirement rule:

Table 3-1 requirement rules for subelement suffixes
Subelement Ending Character	Requirement
*	Can contain zero or more of this subelement.
?	Can contain zero or one of this subelement.
+	Must contain one or more of this subelement.
(none)	Must contain only one of this subelement.

If an element cannot contain other elements, you see EMPTY or (#PCDATA) instead of a list of element names in parentheses.

Data

Some elements contain data instead of subelements. These elements have definitions of the following format:

Attributes

Elements that have ATTLIST tags contain attributes (name-value pairs). Attributes have definitions of the following format:

<!ATTLIST client-container user-name CDATA #REQUIRED
password CDATA #REQUIRED
realm CDATA #IMPLIED>

A client-container element can contain user-name, password, and realm attributes.

The #IMPLIED label means that the attribute is optional, and that Sun Java System Application Server generates a default value. Wherever possible, explicit defaults for optional attributes (such as "true") are listed.

Attribute declarations specify the type of the attribute. For example, CDATA means character data, and %boolean is a predefined enumeration.

J2EE Application Client Deployment Descriptor

Application clients are packaged in JAR format files with a .jar extension and include a deployment descriptor similar to other J2EE application components. The deployment descriptor describes the enterprise beans and external resources referenced by the application. As with other J2EE application components, you need to configure access to resources at the time of deployment, assign names for enterprise beans and resources, etc.The deployment descriptor is standardized by the J2EE 1.3 specification.

Sun Java System Application Client Deployment Descriptor

The sun-application-client.xml is the deployment descriptor for the application clients. The easiest way to create a sun-application-client.xml file is to deploy the application client. For more information on deploying a client using the Administration interface, see the Sun Java System Application Server Developer’s Guide.

Elements in sun-application-client.xml file

Attributes

Elements can contain attributes (name, value pairs). Attributes are defined in attributes lists using the ATTLIST tag.

sun-application-client

This is the root element describing all the runtime bindings of a single application client.

Subelements


Note	Subelements must be defined in the order in which they are listed under each Subelements heading unless otherwise noted.

The following table describes subelements for the sun-application-client element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 3-2 sun-application-client subelements
Element	Required	Description
resource-ref	zero or more	Maps the absolute JNDI name to the resource-ref in the corresponding J2EE XML file.
ejb-ref	zero or more	Maps the absolute JNDI name to the ejb-ref in the corresponding J2EE XML file.
resource-env-ref	zero or more	Maps the absolute JNDI name to the resource-env-ref in the corresponding J2EE XML file.

resource-ref

Maps the absolute JNDI name to the resource-ref element in the corresponding J2EE XML file.

Subelements

The following table describes subelements for the resource-ref element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 3-3 resource-ref subelements
Element	Required	Description
res-ref-name	only one	Specifies the res-ref-name in the corresponding J2EE application-client.xml file.
jndi-name	only one	Specifies the absolute jndi name of a resource.
default-resource-principal	zero or more	Specifies the default principal (user) that the container uses to access a resource.

res-ref-name

Specifies the res-ref-name in the corresponding J2EE application-client.xml file resource-ref entry.

Subelements

default-resource-principal

Specifies the default principal (user) that the container uses to access a resource.

If this element is used in conjunction with a JMS Connection Factory resource, the name and password subelements must be valid entries in Sun Java Message Queue’s broker user repository. See the “Security Management” chapter in the Sun Java System Message Queue Administrator’s Guide for details.

Subelements

The following table describes subelements for the default-resource-principal element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 3-4 default-resource-principal subelements
Element	Required	Description
name	only one	Specifies the name of the principal.
password	only one	Specifies the password for the principal.

name

Subelement

password

Subelement

ejb-ref

Maps the ejb-ref-name in the corresponding J2EE ejb-jar.xml file ejb-ref entry to the absolute jndi-name of a resource.

Subelements

The following table describes subelements for the ejb-ref element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 3-5 ejb-ref subelements
Element	Required	Description
ejb-ref-name	only one	Specifies the name of a ejb reference in the corresponding J2EE appclient.xml file.
jndi-name	only one	Specifies the absolute jndi name of a resource.

ejb-ref-name

Specifies the ejb-ref-name in the corresponding J2EE ejb-ref.xml file ejb-ref entry. This element locates the name of the ejb reference in the application.

Subelement

resource-env-ref

Subelements

The following table describes subelements for the resource-env-ref element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 3-6 resource-env-ref subelements
Element	Required	Description
resource-env-ref-name	only one	Specifies the res-ref-name in the corresponding J2EE application-client.xml file resource-env-ref entry.
default-resource-principal	only one	Specifies the default principal (user) that the container uses to access a resource.
jndi-name	only one	Specifies the jndi-name of the associated entity.

resource-env-ref-name

Specifies the res-ref-name in the corresponding J2EE application-client.xml file resource-env-ref entry.

jndi-name

Contains data that specifies the absolute jndi-name of a URL resource or a resource in the application-client.xml file.

Subelement

Application Client Container Configuration File

The sun-acc.xml file tracks changes in Sun Java System Application Client Container configuration.

Elements in the sun-acc.xml File

client-container

Defines Sun Java System Application Server specific configuration for the ACC. This is the root element; there can only be one client-container element in a sun-acc.xml file.

Subelements

The following table describes subelements for the client-container element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 3-7 client-container subelements
Element	Required	Description
target-server	zero or more	Specifies the IIOP listener configuration of the target server.
auth-realm	only one	Specifies the optional configuration for JAAS authentication realm.
client-credential	only one	Specifies the default client credential that will be sent to the server.
log-service	only one	Specifies the default log file and the severity level of the message.
property	zero or more	Specifies a property which has a name and a value.

Attributes

The following table describes attributes for the client-container element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 3-8 client-container attributes
Attribute	Default Value	Description
sendPassword	none	Specifies whether client authentication credentials should be sent to the server. Without authentication credential all access to protected EJBs will result in exceptions.

target-server

Subelements

The following table describes subelements for the target-server element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 3-9 target-server subelements
Element	Required	Description
description	zero or more	Specifies the description of the target server.
security	zero or more	Specifies the security configuration for the IIOP/SSL communication with the target server.

Attributes

The following table describes attributes for the target-server element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 3-10 target-server attributes
Attribute	Default Value	Description
name	none	Specifies the name of the application server instance accessed by the client container.
address	none	Specifies the host name or IP address (resolvable by DNS) of the ORB.
port	3700	Specifies port number of the ORB. For the new server instance, you need to assign a different port number other than 3700. You can change the port number in the Administration Interface. See the Sun Java System Application Server Administration Guide for more information.

description

Subelement

Attributes

client-credential

Default client credentials that will be sent to the server. If this element is present, then it will be automatically sent to the server, without prompting the user for username and password on the client side.

Subelements

The following table describes subelements for the client-credential element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Attributes

Table 3-11 client-credential subelement
Element	Required	Description
property	zero or more	Specifies a property which has a name and a value.

The following table describes attributes for the client-credential element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 3-12 client-credential attributes
Attribute	Default Value	Description
user-name	none	The user name used to authenticate the Application client container.
password	none	The password used to authenticate the Application client container.
realm	none	The realm (specified by name) where credentials are to be resolved.

log-service

Subelements

The following table describes subelements for the log-service element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Attributes

Table 3-13 log-service subelement
Element	Required	Description
property	zero or more	Specifies a property which has a name and a value.

The following table describes attributes for the log-service element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 3-14 log-service attributes
Attribute	Default Value	Description
file	client.log	Specifies the name of the file where the application client container logging information will be stored. By default, the log file will be located at Appclient_Root/logs/client.log. If the value for the file attribute is set to Null (“ “), the log messages are displayed on the console. The log level is set to the highest level (INFO). Log level can not be set when the output mode is console.
level	none	Sets the base level of severity. Messages at or above this setting get logged into the log file.

security

Defines SSL security configuration for IIOP/SSL communication with the target server.

Subelements

The following table describes subelements for the security element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 3-15 security subelement
Element	Required	Description
ssl	zero or more	Specifies the SSL processing parameters.
cert-db	zero or more	Specifies the location and authentication to read the certification database.

Attributes

ssl

Subelements

Attributes

The following table describes attributes for the SSL element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 3-16 ssl attributes
Attribute	Default Value	Description
cert-nickname	none	The nickname of the server certificate in the certificate database or the PKCS#11 token.In the certificate, the name format is tokenname:nickname. Including the tokenname: part of the name in this attribute is optional.
ssl2-enabled	none	(Optional) Determines whether SSL2 is enabled.
ssl3-enabled	none	(Optional) Determines whether SSL3 is enabled.
ssl2-ciphers	none	(Optional) A space-separated list of the SSL2 ciphers used with the prefix + to enable or - to disable. For example, +rc4. Allowed values are rc4, rc4export, rc2, rc2export, idea, des, desede3.
ssl3-tls-ciphers	none	(Optional) A space-separated list of the SSL3 ciphers used, with the prefix + to enable or - to disable, for example +rsa_des_sha. Allowed SSL3 values are rsa_rc4_128_md5, , rsa_des_sha, rsa_rc4_40_md5, rsa_rc2_40_md5, rsa_null_md5. Allowed TLS values are rsa_des_56_sha, rsa_rc4_56_sha.
tls-enabled	none	Determines whether TLS is enabled.
tls-rollback-enabled	none	Determines whether TLS rollback is enabled.TLS rollback should be enabled for MicroSoft Internet Explorer 5.0 and 5.5.
client-auth-enabled	none	Determines whether SSL3 client authentication is performed on every request, independent of ACL-based access control.

If both SSL2 and SSL3 are enabled, the server tries SSL3 encryption first. If that fails, the server tries SSL2 encryption. If both SSL2 and SSL3 are enabled for a virtual server, the server tries SSL3 encryption first. If that fails, the server tries SSL2 encryption.

cert-db

Location and password to read the certificate database. Sun Java System Application Server provides utilities with which a certificate database can be created. certutil, distributed as part of NSS can also be used to create certificate database.

Subelement

Attributes

The following table describes attributes for the cert-db element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 3-17 cert-db attributes
Attribute	Default Value	Description
cert-db-path	none	Specifies the absolute path of the certificate database (cert7.db).
cert-db-password	none	Specifies the password to access the certificate database.

auth-realm

JAAS is available on the ACC. Defines the optional configuration for JAAS authentication realm.

Authentication realms require provider-specific properties, which vary depending on what a particular implementation needs.

For more information about how to define realms, see the Sun Java System Application Server Developer’s Guide.

Which properties an auth-realm element uses depends on the value of the auth-realm element’s name attribute. The file realm uses file and jaas-context properties. Other realms use different properties.

Subelements

The following table describes subelements for the auth-realm element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Attributes

Table 3-18 auth-realm subelement
Element	Required	Description
property	zero or more	Specifies a property which has a name and a value.

The following table describes attributes for the auth-realm element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 3-19 auth-realm attributes
Attribute	Default Value	Description
auth-realm-name	none	Defines the name of this realm.
classname	none	Defines the Java class which implements this realm.

property

Subelement

Attributes

The following table describes attributes for the property element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 3-20 property attributes
Attribute	Default Value	Description
name	none	Specifies the name of the property.
value	none	Specifies the value of the property.

Previous Contents Index Next
Sun Java System Application Server 7 2004Q2 Update 1 Developer's Guide to Clients