Skip Headers

Oracle9iAS Containers for J2EE Enterprise JavaBeans Developer's Guide and Reference
Release 2 (9.0.2)

Part Number A95881-01
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

A
OC4J-Specific DTD Reference

This appendix describes the elements contained within the OC4J-specific EJB deployment descriptor: orion-ejb-jar.dtd. Some of the elements within this deployment descriptor are too complex for this appendix, so references to another source may be mentioned.

The description of this deployment descriptor has been divided into the following sections:

Whenever you deploy an application, OC4J automatically generates the OC4J-specific XML file with the default elements. If you want to change these defaults, you must copy the orion-ejb-jar.xml file to where your original ejb-jar.xml file is located and change it in this location. If you change the XML file within the deployed location, OC4J simply overwrites these changes when the application is deployed again. The changes only stay constant when changed in the development directories.

Oracle recommends that you add your OC4J-specific XML files within the recommended development structure as shown in Figure A-1.

Figure A-1 Development Application Directory Structure

Text description of dtdxmla.gif follows

Text description of the illustration dtdxmla.gif

OC4J-Specific Deployment Descriptor for EJBs

The OC4J-specific deployment descriptor contains extended deployment information for session beans, entity beans, message driven beans, and security for these EJBs. The major element structure within this deployment descriptor has the following structure:

<orion-ejb-jar deployment-time=... deployment-version=...> 
 <enterprise-beans>
   <session-deployment ...></session-deployment>
   <entity-deployment ...></entity-deployment>
   <message-driven-deployment ...></message-driven-deployment>
   <jem-deployment ...></jem-deployment>
   <jem-server-extension ...></jem-server-extension>
</enterprise-beans>
 <assembly-descriptor>
   <security-role-mapping ...></security-role-mapping>
   <default-method-access></default-method-access>
 </assembly-descriptor>
</orion-ejb-jar>

Each section under the <orion-ejb-jar> main tag has its own purpose. These are described in the sections below:

Enterprise Beans Section

The <enterprise-beans> section defines additional deployment information for all EJBs: session beans, entity beans, and message driven beans. There is a section for each type of EJB.

The following sections describe the elements within <enterprise-beans> element;

Session Bean Section

The <session-bean> section provides additional deployment information for a session bean deployed within this JAR file. The <session-bean> section contains the following structure:

<session-deployment call-timeout=... copy-by-value=... location=...
      max-tx-retries=... name=... persistence-filename=... timeout=...
      wrapper=...
  <env-entry-mapping name=...> </env-entry-mapping
  <ejb-ref-mapping location=... name=... />
  <resource-ref-mapping location=... name=... >
    <lookup-context location=...>
       <context-attribute name=... value=... />
    </lookup-context>
  </resource-ref-mapping>
</session-deployment>

Entity Bean Section

The <entity-bean> section provides additional deployment information for an entity bean deployed within this JAR file. The <entity-bean> section contains the following structure:

<entity-deployment call-timeout=... clustering-schema=... copy-by-value=...
      data-source=... exclusive-write-access=... isolation=... location=...
      max-tx-retries=... name=... table=... validity-timeout=... wrapper=...>
  <primkey-mapping>
   <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
      persistence-type=...></cmp-field-mapping>
  </primkey-mapping>
  <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
      persistence-type=...> </cmp-field-mapping>
  <finder-method partial=... query=... >
   <method></method>
  </finder-method>
  <env-entry-mapping name=...></env-entry-mapping>
  <ejb-ref-mapping location=... name=... />
  <resource-ref-mapping location=... name=... >
    <lookup-context location=...>
       <context-attribute name=... value=... />
    </lookup-context>
  </resource-ref-mapping>
</entity-deployment>

Message Driven Bean Section

The <message-driven-bean> section provides additional deployment information for a message driven bean deployed within this JAR file. The <message-driven-bean> section contains the following structure:

<message-driven-deployment connection-factory-location=... 
destination-location=... name=...> <env-entry-mapping name=...></env-entry-mapping> <ejb-ref-mapping location=... name=... /> <resource-ref-mapping location=... name=... > <lookup-context location=...> <context-attribute name=... value=... /> </lookup-context> </resource-ref-mapping> </message-driven-deployment>

AC4J Active EJB Section

The <jem-server-extension> section defines the JNDI name of the database where the AC4J Databus is installed. The <jem-server-extension> contains the following structure:

<jem-server-extension data-source-location=...>
  <description></description>
</jem-server-extension>

The <jem-deployment> section provides additional deployment information for an active EJB deployed within this JAR file. The <jem-deployment> section contains the following structure:

 <jem-deployment jem-name=... ejb-name=...>
   <description></description>
   <called-by>
     <caller  caller-identity=.../>  
   </called-by>
   <security-identity>
    <description></description>
    <use-caller-identity></use-caller-identity>
   </security-identity>
 </jem-deployment>

CMP Field Mapping Section

The mapping of logical names to actual names can be a complex process. See "Object-Relational Mapping of Persistent Fields" for a discussion on mapping CMP data fields.

The following are the XML elements used for CMP persistent data field mapping within the orion-ejb-jar.xml file:

<cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
      persistence-type=...>
   <fields> 
      <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
          persistence-type=...></cmp-field-mapping>
   </fields>
   <properties> 
      <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
            persistence-type=...></cmp-field-mapping>
   </properties>
   <entity-ref home=...> 
      <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
          persistence-type=...></cmp-field-mapping>
   </entity-ref>
   <list-mapping table=...> 
      <primkey-mapping>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </primkey-mapping>
      <value-mapping immutable="true|false" type=...>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </value-mapping>
   </list-mapping>
   <collection-mapping table=...>
      <primkey-mapping>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </primkey-mapping>
      <value-mapping immutable="true|false" type=...>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </value-mapping>
   </collection-mapping>
   <set-mapping table=...>
      <primkey-mapping>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </primkey-mapping>
      <value-mapping immutable="true|false" type=...>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </value-mapping>
   </set-mapping>
   <map-mapping table=...>
      <primkey-mapping>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </primkey-mapping>
      <map-key-mapping type=...>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </map-key-mapping>
      <value-mapping immutable="true|false" type=...>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </value-mapping>
   </map-mapping>
</cmp-field-mapping>

Method Definition

The following structure is used to specify the methods (and possibly parameters of that method) of the bean.

<method>
   <description></description>
   <ejb-name></ejb-name>
   <method-intf></method-intf>
   <method-name></method-name>
   <method-params>
     <method-param></method-param>
   </method-params>
</method>

The style used can be one of the following:

  1. When referring to all the methods of the specified enterprise bean's home and remote interfaces, specify the methods as follows:

        <method>
                <ejb-name>EJBNAME</ejb-name>
                <method-name>*</method-name>
        </method>
    
    
  2. When referring to multiple methods with the same overloaded name, specify the methods as follows:

       	<method>
    	<ejb-name>EJBNAME</ejb-name>
       		<method-name>METHOD</method-name>
    	</method>>
    
    
  3. When referring to a single method within a set of methods with an overloaded name, you can specify each parameter within the method as follows:

     	<method>
    	<ejb-name>EJBNAME</ejb-name>
    		<method-name>METHOD</method-name>
    			<method-params>
    			 	<method-param>PARAM-1</method-param>
    			   	<method-param>PARAM-2</method-param>
    			          			...
    			   	<method-param>PARAM-n</method-param>
    			</method-params>
    	<method>	
    

Assembly Descriptor Section

In addition to specifying deployment information for individual beans, you can also specify addition deployment information for security in the <assembly-descriptor> section. The <assembly-descriptor> section contains the following structure:

<assembly-descriptor>
  <security-role-mapping impliesAll=... name=...>
   <group name=... />
   <user name=... />
  </security-role-mapping>
  <default-method-access>
   <security-role-mapping impliesAll=... name=...>
    <group name=... />
    <user name=... />
   </security-role-mapping>    
  </default-method-access>
</assembly-descriptor>

DTD Listing

The following lists the orion-ejb-jar.xml DTD to show the ordering required, and optional parameters for each element. The definitions for each element is described in "Element Description".

<!ELEMENT properties (cmp-field-mapping*)>
<!ELEMENT fields (cmp-field-mapping*)>
<!ELEMENT session-deployment (env-entry-mapping*, ejb-ref-mapping*,
  resource-ref-mapping*)>
<!ATTLIST session-deployment call-timeout CDATA #IMPLIED
  copy-by-value CDATA #IMPLIED
  location CDATA #IMPLIED
  max-tx-retries CDATA #IMPLIED
  name CDATA #IMPLIED
  persistence-filename CDATA #IMPLIED
  timeout CDATA #IMPLIED
  wrapper CDATA #IMPLIED
  replication CDATA #IMPLIED>
<!ELEMENT collection-mapping (primkey-mapping, value-mapping)>
<!ATTLIST collection-mapping table CDATA #IMPLIED>
<!ELEMENT resource-ref-mapping (lookup-context?)>
<!ATTLIST resource-ref-mapping location CDATA #IMPLIED
  name CDATA #REQUIRED>
<!ELEMENT method-intf (#PCDATA)>
<!ELEMENT entity-ref (cmp-field-mapping)>
<!ATTLIST entity-ref home CDATA #IMPLIED>
<!ELEMENT enterprise-beans ((session-deployment | entity-deployment | 
  message-driven-deployment | jem-deployment)+, jem-server-extension?)>
<!ELEMENT ejb-ref-mapping (#PCDATA)>
<!ATTLIST ejb-ref-mapping location CDATA #IMPLIED
  name CDATA #REQUIRED>
<!ELEMENT primkey-mapping (cmp-field-mapping)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT env-entry-mapping (#PCDATA)>
<!ATTLIST env-entry-mapping name CDATA #IMPLIED>
<!ELEMENT security-role-mapping (group*, user*)>
<!ATTLIST security-role-mapping impliesAll CDATA #IMPLIED
  name CDATA #IMPLIED>
<!ELEMENT method-params (method-param*)>
<!ELEMENT cmp-field-mapping 
  (fields|properties|entity-ref|list-mapping|collection-mapping|set-mapping|
  map-mapping|field-persistence-manager)?>
<!ATTLIST cmp-field-mapping ejb-reference-home CDATA #IMPLIED
  name CDATA #IMPLIED
  persistence-name CDATA #IMPLIED
  persistence-type CDATA #IMPLIED>
<!ELEMENT list-mapping (primkey-mapping, value-mapping)>
<!ATTLIST list-mapping table CDATA #IMPLIED>
<!ELEMENT group (#PCDATA)>
<!ATTLIST group name CDATA #IMPLIED>
<!ELEMENT default-method-access (security-role-mapping)>
<!ELEMENT map-key-mapping (cmp-field-mapping)>
<!ATTLIST map-key-mapping type CDATA #IMPLIED>
<!ELEMENT map-mapping (primkey-mapping, map-key-mapping, value-mapping)>
<!ATTLIST map-mapping table CDATA #IMPLIED>
<!ELEMENT value-mapping (cmp-field-mapping)>
<!ATTLIST value-mapping immutable CDATA #IMPLIED
  type CDATA #IMPLIED>
<!ELEMENT method-param (#PCDATA)>
<!ELEMENT user (#PCDATA)>
<!ATTLIST user name CDATA #IMPLIED>
<!ELEMENT lookup-context (context-attribute+)>
<!ATTLIST lookup-context location CDATA #IMPLIED>
<!ELEMENT context-attribute (#PCDATA)>
<!ATTLIST context-attribute name CDATA #IMPLIED
  value CDATA #IMPLIED>
<!ELEMENT set-mapping (primkey-mapping, value-mapping)>
<!ATTLIST set-mapping table CDATA #IMPLIED>
<!ELEMENT message-driven-deployment (env-entry-mapping*, ejb-ref-mapping*, 
  resource-ref-mapping*)>
<!ATTLIST message-driven-deployment cache-timeout CDATA #IMPLIED
  connection-factory-location CDATA #IMPLIED
  destination-location CDATA #IMPLIED
  max-instances CDATA #IMPLIED
  min-instances CDATA #IMPLIED
  name CDATA #IMPLIED>
<!ELEMENT jem-server-extension (description?, data-bus?)>
<!ATTLIST jem-server-extension
  data-source-location CDATA #REQUIRED
  scheduling-threads CDATA #IMPLIED>
<!ELEMENT data-bus EMPTY>
<!ATTLIST data-bus
  data-bus-name CDATA #REQUIRED
  url CDATA #IMPLIED>
<!ELEMENT jem-deployment (description?, data-bus?, called-by,   
  security-identity)>
<!ATTLIST jem-deployment
  jem-name CDATA #REQUIRED
  ejb-name CDATA #REQUIRED>
<!ELEMENT called-by (caller+)>
<!ELEMENT caller EMPTY>
<!ATTLIST caller
  caller-identity CDATA #REQUIRED>
<!ELEMENT security-identity   
  (description?,(use-caller-identity|run-as-specified-identity))>
<!ELEMENT use-caller-identity EMPTY>
<!ELEMENT run-as-specified-identity (description?, role-name)>
<!ELEMENT role-name (#PCDATA)>
<!ELEMENT ejb-name (#PCDATA)>
<!ELEMENT field-persistence-manager (property)>
<!ATTLIST field-persistence-manager class CDATA #IMPLIED>
<!ELEMENT property (#PCDATA)>
<!ATTLIST property name CDATA #IMPLIED
  value CDATA #IMPLIED>
<!ELEMENT finder-method (method)>
<!ATTLIST finder-method partial CDATA #IMPLIED
  query CDATA #IMPLIED>
<!ELEMENT method (description?, ejb-name, method-intf?, method-name, 
  method-params?)>
<!ELEMENT entity-deployment (primkey-mapping?, cmp-field-mapping*, 
  finder-method*, env-entry-mapping*, ejb-ref-mapping*, resource-ref-mapping*)>
<!ATTLIST entity-deployment call-timeout CDATA #IMPLIED
  clustering-schema CDATA #IMPLIED
  copy-by-value CDATA #IMPLIED
  data-source CDATA #IMPLIED
  exclusive-write-access CDATA #IMPLIED
  instance-cache-timeout CDATA #IMPLIED
  location CDATA #IMPLIED
  isolation (commited | serializable | uncommited | repeatable_reads) 
    CDATA #IMPLIED
  locking-mode (pessimistic | optimistic | read-only | old_pessimistic)
  max-instances CDATA #IMPLIED
  min-instances CDATA #IMPLIED
  max-instances-per-pk CDATA #IMPLIED
  min-instances-per-pk CDATA #IMPLIED
  max-tx-retries CDATA #IMPLIED
  update-changed-fields-only (true | false) "true"
  name CDATA #IMPLIED
  pool-cache-timeout CDATA #IMPLIED
  table CDATA #IMPLIED
  validity-timeout CDATA #IMPLIED
  wrapper CDATA #IMPLIED>
<!ELEMENT orion-ejb-jar (enterprise-beans, assembly-descriptor)>
<!ATTLIST orion-ejb-jar deployment-time CDATA #IMPLIED
  deployment-version CDATA #IMPLIED>
<!ELEMENT assembly-descriptor (security-role-mapping*, default-method-access?)>
<!ELEMENT method-name (#PCDATA)>

Element Description

<assembly-descriptor>

The mapping of the assembly descriptor elements.

<cmp-field-mapping>

Deployment information for a container-managed persistence field. If no subtags are used to define different behavior, the field is persisted through serialization or native handling of "recognized" primitive types.

Attributes:

<collection-mapping>

Specifies a relational mapping of a Collection type. A Collection consists of n unordered items (order isnt specified and not relevant). The field containing the mapping must be of type java.util.Collection.

Attiributes:

<context-attribute>

An attribute sent to the context. The only mandatory attribute in JNDI is the 'java.naming.factory.initial' which is the classname of the context factory implementation.

Attributes:

<default-method-access>

The default method access policy for methods not tied to a method-permission.

<description>

A short description.

<ejb-name>

The ejb-name element specifies an enterprise bean's name. This name is assigned by the ejb-jar file producer to name the enterprise bean in the ejb-jar file's deployment descriptor. The name must be unique among the names of the enterprise beans in the same ejb-jar file. The enterprise bean code does not depend on the name; therefore the name can be changed during the application-assembly process without breaking the enterprise bean's function. There is no architected relationship between the ejb-name in the deployment descriptor and the JNDI name that the Deployer will assign to the enterprise bean's home. The name must conform to the lexical rules for an NMTOKEN.

<ejb-ref-mapping>

The ejb-ref element that is used for the declaration of a reference to another enterprise bean's home. The ejb-ref-mapping element ties this to a JNDI-location when deploying.

Attributes:

<enterprise-beans>

The beans contained in this EJB JAR file.

<entity-deployment>

Deployment information for an entity bean.

Attributes:

<entity-ref>

Specified the configuration for persisting an entity reference via it's primary key. The child-tag of this tag is the specification of how to persist the primary key.

Attributes:

<env-entry-mapping>

Overrides the value of an env-entry in the assembly descriptor. It is used to keep the EAR clean from deployment-specific values. The body is the value.

Attribute:

<fields>

Specifies the configuration of a field-based (java class field) mapping persistence for this field. The fields that are to be persisted have to be public, non-static, non-final and the type of the containing object has to have an empty constructor.

<finder-method>

The definition of a container-managed finder method. This defines the selection criteria in a findByXXX() method in the bean's home.

Attributes:

<group>

A group that this <security-role-mapping> implies. That is, all members of the specified group are included in this role.

Attributes:

<jem-deployment>

Specifies an active EJB for deployment into the AC4J container.

Attributes:

<jem-server-extension>

Describes the database server where the Databus is installed

Attributes:

<list-mapping>

Specifies a relational mapping of a List type. A List is a sequential (where order/index is important) Collection of items. The field containing the mapping must be of type java.util.List or the legacy types java.util.Vector or Type[].

Attributes:

<lookup-context>

The specification of an optional javax.naming.Context implementation used for retrieving the resource. This is useful when using third party modules, such as a third party JMS server. Either use the context implementation supplied by the resource vendor or, if none exists, write an implementation that negotiates with the vendor software.

Attribute:

<map-key-mapping>

Specifies a mapping of the map key. Map keys are always immutable.

Attributes:

<map-mapping>

Specifies a relational mapping of a Map type. A Map consists of n unique keys and their mapping to values. The field containing the mapping must be of type java.util.Map or the legacy types java.util.Hashtable or java.util.Properties.

Attributes:

<message-driven-deployment>

Deployment information for a MDB.

Attributes:

<method>

Specify the methods (and possibly parameters of that method) of the bean.

<method-intf>

The method-intf element allows a method element to differentiate between the methods with the same name and signature that are defined in both the remote and home interfaces. The method-intf element must be one of the following: Home or Remote.

<method-name>

The method-name element contains a name of an enterprise bean method, or the asterisk (*) character. The asterisk is used when the element denotes all the methods of an enterprise bean's remote and home interfaces.

<method-param>

The method-param element contains the fully-qualified Java type name of a method parameter.

<method-params>

The method-params element contains a list of the fully-qualified Java type names of the method parameters.

<orion-ejb-jar>

An orion-ejb-jar.xml file contains the OC4J-specific deployment information for an EJB. It is used to specify initial deployment properties. After each deployment the deployment file is reformatted and altered by the server for additional information.

Attributes:

<primkey-mapping>

Designates how the primary key is mapped.

<properties>

Specifies the configuration of a property-based (bean properties) mapping persistence for this field. The properties have to adhere to the usual JavaBeans specification and the type of the containing object has to have an empty constructor This is also designated within the EJB specification.

<resource-ref-mapping>

The resource-ref element is used for the declaration of a reference to an external resource such as a data source, JMS queue, or mail session. The resource-ref-mapping ties this to a JNDI-location when deploying.

Attributes:

<security-role-mapping>

The runtime mapping (to groups and users) of a role. Maps to a security-role of the same name in the assembly descriptor.

Attributes:

<session-deployment>

Deployment information for a session bean.

Attributes:

<set-mapping>

Specifies a relational mapping of a Set type. A Set consists of n unique unordered items (order is not specified and not relevant). The field containing the mapping must be of type java.util.Set.

Attributes:

<user>

A user that this security-role-mapping implies.

Attributes:

<value-mapping>

Specified a mapping of the primary key part of a set of fields.

Attributes:


Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index