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

> ## 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
> - J2EE Application Client Deployment Descriptor
> - Sun Java System Application Client Deployment Descriptor
> - Application Client Container Configuration File

> ##

> 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:

> - A J2EE standard file (application.client.xml), described in the J2EE Specification.
> - An optional Sun Java System Application Server specific client deployment descriptor file (sun-application-client.xml), described in this section.
> - An optional Sun Java System Application Server specific Application Client Container Configuration file (sun-acc.xml), described in this section.

> ### 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.

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

> For general information about DTD files and XML, see the XML specification at:

> http://www.w3.org/TR/REC-xml

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

> - Subelements
> - Data
> - Attributes

> #### Subelements

> 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:

> <!ELEMENT element-name (#PCDATA)>

> For example:

> <!ELEMENT credential (#PCDATA)>

> #### Attributes

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

> <!ATTLIST element attribute type default attribute type default ...>

> For example:

> <!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 #REQUIRED label means that a value must be supplied.

> 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

> Elements in the sun-application-client.xml file are as follows:

> - sun-application-client
> - resource-ref
> - ejb-ref
> - resource-env-ref
> - res-ref-name
> - resource-env-ref-name
> - default-resource-principal
> - name
> - password
> - ejb-ref-name
> - jndi-name

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

> ##### Attributes

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

> None of the elements in the sun-application-client.xml file contain attributes.

> ### sun-application-client

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

> ##### Subelements

> 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

> none

> ### 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

> Contains data that specifies the name of the principal.

> ##### Subelement

> none

> ### password

> Contains data that specifies the password for the principal.

> ##### Subelement

> none

> ### 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

> none

> ### resource-env-ref

> Specifies the name of a resource env reference.

> ##### 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.

> Subelements

> none

> ### jndi-name

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

> ##### Subelement

> none

> ##

> 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

> Elements in the sun-acc.xml file are as follows:

> - client-container
> - target-server
> - description
> - client-credential
> - log-service
> - security
> - ssl
> - cert-db
> - auth-realm
> - property

> ### 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

> Defines the IIOP listener configuration of the 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

> Contains data that specifies a text description of the containing element.

> ##### Subelement

> none

> ##### Attributes

> none

> ### 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.

> Table 3-11 client-credential subelement

> Element | Required | Description
> --- | --- | ---
> property | zero or more | Specifies a property which has a name and a value.

> ##### Attributes

> 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

> Specifies configuration settings for the log file.

> ##### 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.

> Table 3-13 log-service subelement

> Element | Required | Description
> --- | --- | ---
> property | zero or more | Specifies a property which has a name and a value.

> ##### Attributes

> 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

> none

> ### ssl

> Defines SSL processing parameters.

> ##### Subelements

> none

> ##### 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

> none

> ##### 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.

> Here is an example of the default file realm:

> <auth-realm name="file"

> classname="com.iplanet.ias.security.auth.realm.file.FileRealm">

> <property name="file" value="instance_dir/config/keyfile"/>

> <property name="jaas-context" value="fileRealm"/>

> </auth-realm>

> 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.

> Table 3-18 auth-realm subelement

> Element | Required | Description
> --- | --- | ---
> property | zero or more | Specifies a property which has a name and a value.

> ##### Attributes

> 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

> Specifies a property, which has a name and a value.

> ##### Subelement

> none

> ##### 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

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.