A Client Application Deployment Descriptor Elements

This appendix describes deployment descriptors for Java EE client applications supported by WebLogic Server.

This appendix includes the following sections:

Overview of Client Application Deployment Descriptor Elements

When it comes to Java EE applications, often users are only concerned with the server-side modules (Web applications, EJBs, and connectors). You configure these server-side modules using the application.xml deployment descriptor, discussed in "Enterprise Application Deployment Descriptor Elements" in Developing Applications for Oracle WebLogic Server.

However, it is also possible to include a client module (a JAR file) in an EAR file. This JAR file is only used on the client side; you configure this client module using the application-client.xml deployment descriptor. This scheme makes it possible to package both client and server side modules together. The server looks only at the parts it is interested in (based on the application.xml file) and the client looks only at the parts it is interested in (based on the application-client.xml file).

For client-side modules, two deployment descriptors are required: a Java EE standard deployment descriptor, application-client.xml, and a WebLogic-specific run time deployment descriptor with a name derived from the client application JAR file.

application-client.xml Deployment Descriptor Elements

The application-client.xml file is the deployment descriptor for Java EE client applications. It must begin with the following DOCTYPE declaration:

<!DOCTYPE application-client PUBLIC "-//Sun Microsystems, 
Inc.//DTD Java EE Application Client 1.2//EN" 
"http://java.sun.com/j2ee/dtds/application-client_1_2.dtd">

The following sections describe each of the elements that can appear in the file.

application-client

application-client is the root element of the application client deployment descriptor. The application client deployment descriptor describes the EJB modules and other resources used by the client application.

The following table describes the elements you can define within an application-client element.

Table A-1 application-client Elements

Element Description

<icon>

Optional. Locations of small and large images that represent the application in a GUI tool. This element is not currently used by WebLogic Server.

<display-name>

Application display name, a short name that is intended to be displayed by GUI tools.

<description>

Optional. Description of the client application.

<env-entry>

Contains the declaration of a client application's environment entries.

Elements you can define within a env-entry element are:

  • description—Optional. Contains a description of the particular environment entry.

  • env-entry-name—Contains the name of a client application's environment entry.

  • env-entry-type—Contains the fully qualified Java type of the environment entry. The possible values are: java.lang.Boolean, java.lang.String, java.lang.Integer, java.lang.Double, java.lang.Byte, java.lang.Short, java.lang.Long, and java.lang.Float.

  • env-entry-value—Optional. Contains the value of a client application's environment entry. The value must be a String that is valid for the constructor of the specified env-entry-type.

<ejb-ref>

Used for the declaration of a reference to an EJB referenced in the client application.

Elements you can define within an ejb-ref element are:

  • description—Optional. Provides a description of the referenced EJB.

  • ejb-ref-name—Contains the name of the referenced EJB. Typically the name is prefixed by ejb/, such as ejb/Deposit.

  • ejb-ref-type—Contains the expected type of the referenced EJB, either Session or Entity.

  • home—Contains the fully-qualified name of the referenced EJB's home interface.

  • remote—Contains the fully-qualified name of the referenced EJB's remote interface.

  • ejb-link—Specifies that an EJB reference is linked to an Enterprise Java Bean in the Java EE application package. The value of theejb-link element must be the name of the ejb-name of an EJB in the same Java EE application.

<resource-ref>

Contains a declaration of the client application's reference to an external resource.

Elements you can define within a resource-ref element are:

  • description—Optional. Contains a description of the referenced external resource.

  • res-ref-name—Specifies the name of the resource factory reference name. The resource factory reference name is the name of the client application's environment entry whose value contains the JNDI name of the data source.

  • res-type—Specifies the type of the data source. The type is specified by the Java interface or class expected to be implemented by the data source.

  • res-auth—Specifies whether the EJB code signs on programmatically to the resource manager, or whether the container will sign on to the resource manager on behalf of the EJB. In the latter case, the container uses information that is supplied by the deployer. The res-auth element can have one of two values: Application or Container.

weblogic-appclient.xml Descriptor Elements

This XML-formatted deployment descriptor is not stored inside of the client application JAR file like other deployment descriptors, but must be in the same directory as the client application JAR file.

The file name for the deployment descriptor is the base name of the JAR file, with the extension .runtime.xml. For example, if the client application is packaged in a file named c:/applications/ClientMain.jar, the run-time deployment descriptor is in the file named c:/applications/ClientMain.runtime.xml.

application-client

The application-client element is the root element of a WebLogic-specific run-time client deployment descriptor. The following table describes the elements you can define within an application-client element.

Table A-2 application-client Elements

Element Description

<env-entry>

Specifies values for environment entries declared in the deployment descriptor.

Elements you can define within a env-entry element are:

  • env-entry-name—Name of an application client's environment entry. Example: <env-entry-name>EmployeeAppDB</env-entry-name>

  • env-entry-value—Value of an application client's environment entry. The value must be a valid String for the constructor of the specified type, which takes a single String parameter.

<ejb-ref>

Specifies the JNDI name for a declared EJB reference in the deployment descriptor.

Elements you can define within an ejb-ref element are:

  • ejb-ref-name—Name of an EJB reference. The EJB reference is an entry in the application client's environment. Oracle recommends that name is prefixed withejb/. Example: <ejb-ref-name>ejb/Payroll</ejb-ref-name>.

  • jndi-name—JNDI name for the EJB.

<resource-ref>

Declares an application client's reference to an external resource. It contains the resource factory reference name, an indication of the resource factory type expected by the application client's code, and the type of authentication (bean or container).

Example:

<resource-ref>

<res-ref-name>EmployeeAppDB</res-ref-name>

<jndi-name>enterprise/databases/HR1984</jndi-name>

</resource-ref>

Elements you can define within a resource-ref element are:

  • res-ref-name—Name of the resource factory reference name. The resource factory reference name is the name of the application client's environment entry whose value contains the JNDI name of the data source.

  • jndi-name—JNDI name for the resource.

<resource-description>

Maps the JNDI name of a server resource to an EJB resource reference in WebLogic Server.

Elements you can define within a resource-description element are:

  • res-ref-name—Specifies the name of a resource reference.

  • jndi-name—Specifies a JNDI name for the resource.

<resource-env-description>

Maps a resource-env-ref, declared in the ejb-jar.xml deployment descriptor, to the JNDI name of the server resource it represents.

Elements you can define within a resource-env-description element are:

  • res-env-ref-name—Specifies the name of a resource environment reference.

  • jndi-name—Specifies a JNDI name for the resource environment reference.

<ejb-reference-description>

Elements you can define within an ejb-reference-description element are:

  • ejb-ref-name—Specifies the name of an EJB reference used in your Web application.

  • jndi-name—Specifies a JNDI name for the reference.

<service-reference-description>

Elements you can define within an ejb-reference-description element are:

  • service-ref-name

  • wsdl-url

  • call-property—The call-property element has the following sub-elements:

    • name

    • value

  • port-info—The port-info element has the following sub-elements:

    • port-name

    • stub-property

    • call-property