ejb-j2ee-engine.dtd (SAP Library

ejb-j2ee-engine.dtd

Definition

A document type definition (DTD) that describes how you specify additional information about enterprise beans. This information is specified here, because the EJB Specification does not explicitly define the exact element names that should be used. This XML is optional for session and entity beans. However, it is required if your EJB application contains message-driven beans, because it contains information, without which the beans cannot work.

Structure

The ejb-j2ee-engine.dtd defines the following elements:

This graphic is explained in the accompanying text

The usage of each element is explained below:

<!--

The root element of this deployment descriptor. It contains additional information about the enterprise beans in your application.

-->

<!ELEMENT ejb-j2ee-engine (description?, enterprise-beans?, transaction-descriptor?, security-permission?)>

<!--

Description of the contents of this XML.

-->

<!ELEMENT description (#PCDATA)>

<!--

Describes enterprise beans’ deployment specifics.

-->

<!ELEMENT enterprise-beans (enterprise-bean+)>

<!ELEMENT enterprise-bean (ejb-name, jndi-name?, container-size?, ejb-ref*, ejb-local-ref*, resource-ref*, resource-env-ref*, server-component-ref*, run-as-identity-map?, ior-security-config*, (session-props|entity-props|message-props)?)>

<!--

The name of the enterprise bean. It is the same as the ejb-name specified in the ejb-jar.xml file. This name must be unique among the enterprise bean names in the JAR.

-->

<!ELEMENT ejb-name (#PCDATA)>

<!--

The name, under which the bean must be registered in the JNDI and with which it can be looked up. If this element is not specified, the bean will be registered by applicationName/ejb-name.

-->

<!ELEMENT jndi-name (#PCDATA)>

<!--

The initial size of the EJB Container when the bean is loaded.

-->

<!ELEMENT container-size (#PCDATA)>

<!--

Specifies the remote references that the EJB application has to other enterprise beans. These references are defined in the <ejb-ref> element in ejb-jar.xml. This element specifies the JNDI name of the referenced enterprise bean.

Example:

    <ejb-ref>
        <ejb-ref-name>myEJBRef</ejb-ref-name>
        <jndi-name>ReferencedEJBJNDIName</jndi-name>
    </ejb-ref>

-->

<!ELEMENT ejb-ref (ejb-ref-name, jndi-name)>

<!--

The name of the referenced enterprise bean as defined in ejb-jar.xml.

-->

<!ELEMENT ejb-ref-name (#PCDATA)>

<!--

The name under which the referenced enterprise bean must be registered in the JNDI and with which it can be looked up. The value of this element must be as follows:

· if you have specified a custom JNDI name for your enterprise bean using the <jndi-name> tag of the ejb-j2ee-engine.xml descriptor, the value of this tag must be the same.

· if you have not specified a custom JNDI name for your enterprise bean, then the JNDI name of the bean has the following format: applicationName/ejb-name.

-->

<!ELEMENT jndi-name (#PCDATA)>

<!--

Specifies the local references that the EJB application has to other enterprise beans. These references are defined in the <ejb-local-ref> element in ejb-jar.xml. This element specifies the JNDI name of the referenced enterprise bean.

Example:

    <ejb-local-ref>
        <ejb-ref-name>myEJBLocalRef</ejb-ref-name>
        <jndi-name>ReferencedEJBJNDIName</jndi-name>
    </ejb-local-ref>
-->

<!ELEMENT ejb-local-ref (ejb-ref-name, jndi-name)>

<!--

The name of the referenced enterprise bean as defined in ejb-jar.xml.

-->

<!ELEMENT ejb-ref-name (#PCDATA)>

<!--

The name under which the referenced enterprise bean must be registered in the JNDI and with which it can be looked up. The value of this element must be as follows:

· if you have specified a custom JNDI name for your enterprise bean using the <jndi-name> tag of the ejb-j2ee-engine.xml descriptor, the value of this tag must be the same.

· if you have not specified a custom JNDI name for your enterprise bean, then the JNDI name of the bean has the following format: applicationName/ejb-name.

-->

<!ELEMENT jndi-name (#PCDATA)>

<!--

Specifies the resource references of the EJB application. These references are defined in ejb-jar.xml. This element specifies the JNDI name of the referenced resource.

Example:

    <resource-ref>
        <res-ref-name>myResourceRef</res-ref-name>
        <res-link>ReferencedResourceJNDIName</res-link>
        <non-transactional/>
    </resource-ref>

-->

<!ELEMENT resource-ref (res-ref-name, res-link, non-transactional?)>

<!--

The name of the resource that is referenced by the bean. This name is defined in ejb-jar.xml.

-->

<!ELEMENT res-ref-name (#PCDATA)>

<!--

The name under which the resource must be registered in the JNDI and with which it can be looked up. The value of this tag depends on the type of the referenced resource:

· for resources of type javax.sql.DataSource it is either the value of the <data-source-name>, or the value of the <alias> tag you specified in the data-sources.xml descriptor. Or if you have used the data-source-aliases.xml instead, the value of this tag must be the same as the value of the <alias> tag for the corresponding DataSource.

· for resources of type javax.jms.QueueConnectionFactory and javax.jms.TopicConnectionFactory it is either the value of the <factory-name>, or the value of the <alias> tag you specified in the jms-factories.xml descriptor.

· for resources of type javax.resource.cci.ConnectionFactory it is either the value of the <jndi-name> tag, or the value of the <alias> tag you specified in the connector-j2ee-engine.xml descriptor. Or, if you have not used the connector-j2ee-engine.xml descriptor at all (since it is not mandatory), the value of this tag is equivalent to the name of the corresponding RAR file (not including the .rar file extension).

-->

<!ELEMENT res-link (#PCDATA)>

<!--

If this element exists, sets the resource reference as non-transactional. By default the resource is transactional.

-->

<!ELEMENT non-transactional EMPTY>

<!--

Specifies the resource environment references of the EJB application. These references are defined in ejb-jar.xml. This element specifies the JNDI name of the referenced environment resource.

Example:

    <resource-env-ref>
        <res-env-ref-name>myEnvResourceName</res-env-ref-name>
        <jndi-name>ReferencedEnvResourceJNDIName</jndi-name>
    </resource-env-ref>
-->

<!ELEMENT resource-env-ref (res-env-ref-name, jndi-name)>

<!--

The name of the environment resource as defined in ejb-jar.xml.

-->

<!ELEMENT res-env-ref-name (#PCDATA)>

<!--

The name under which the environment reference must be registered in the JNDI and with which it can be looked up. The value of this element must be the same as the name of the resource environment entry that you have specified in the <destination-name> element of the jms-destinations.xml descriptor.

-->

<!ELEMENT jndi-name (#PCDATA)>

<!--

Specifies a reference from the application to a service, interface, or library.

Example:

    <server-component-ref>
        <description>This element describes an application reference to the myInterface interface</description>
        <name>myInterface</name>
        <type>interface</type>
        <jndi-name>ReferencedInterfaceJNDIName</jndi-name>
    </server-component-ref>
-->

<!ELEMENT server-component-ref (description?, name, type, jndi-name)>

<!--

The name with which the resource will be looked up.

-->

<!ELEMENT name (#PCDATA)>

<!--

The type of the reference – the value of this element can be service or interface.

-->

<!ELEMENT type (#PCDATA)>

<!--

The name under which the resource is registered in the JNDI.

-->

<!ELEMENT jndi-name (#PCDATA)>

<!--

The name of the security principal that will be used if the run-as identity is specified in the bean’s ejb-jar.xml. If this element is omitted, the EJB Container will choose a random user, mapped to the one specified in the ejb-jar.xml security role.

Example:

    <run-as-identity-map>
        <user-name>Administrator</user-name>
    </run-as-identity-map>
-->

<!ELEMENT run-as-identity-map (user-name)>

<!--

Specifies the security mechanisms that are supported by the SAP J2EE Engine when a look up using IIOP is performed. These mechanisms are used according to Conformance Level 0 defined in the OMG’s Common Secure Interoperability V2 Specification.

-->

<!ELEMENT ior-security-config (transport-config?, as-context?, sas-context?)>

<!--

Defines the transport-layer security mechanism, that is, it defines the transport protocol and its configuration.

-->

<!ELEMENT transport-config (integrity, confidentiality, establish-trust-in-target, establish-trust-in-client)>

<!--

Specifies how the target processes integrity protected messages, that is, whether the SAP J2EE Engine uses SSL during the course of the message process. The values of this element can be: required (SAP J2EE Engine uses SSL during the course of message process), supported (SAP J2EE Engine can use SSL during the course of message process), and none (SAP J2EE Engine does not use SSL during the course of message process).

-->

<!ELEMENT integrity (#PCDATA)>

<!--

Specifies whether the privacy protected messages will be encrypted. The values of this element can be: required (SAP J2EE Engine encrypts the messages), supported (SAP J2EE Engine provides options for encrypting the messages), and none (SAP J2EE Engine does not encrypt the messages).

-->

<!ELEMENT confidentiality (#PCDATA)>

<!--

Specifies whether the SAP J2EE Engine authenticates to the client. The values of this element can be: supported (SAP J2EE Engine provides options for authentication to the client), and none (SAP J2EE Engine does not support authentication to the client).

-->

<!ELEMENT establish-trust-in-target (#PCDATA)>

<!--

Specifies whether the SAP J2EE Engine authenticates the client. The values of this element can be: required (SAP J2EE Engine accepts connections only from clients who successfully authenticate in the handshake), supported (SAP J2EE Engine provides options for client authentication), and none (SAP J2EE Engine does not support client authentication).

-->

<!ELEMENT establish-trust-in-client (#PCDATA)>

<!--

Describes the authentication context.

-->

<!ELEMENT as-context (auth-method, realm, required)>

<!--

Specifies whether an authentication context will be used. The values of this element can be: username_password (the client must specify username and password when logging), and none (the as_context will not be used; authentication using transport level(s) or identity assertion will be used instead).

-->

<!ELEMENT auth-method (#PCDATA)>

<!--

The name of the realm, for which the specified username and password apply, if the authentication mechanism is used. The values of this element can be: default (the username and password apply to the whole realm) and none (the username and password do not apply to the current realm).

-->

<!ELEMENT realm (#PCDATA)>

<!--

Specifies whether this authentication method is required or optional. The values of this element can be: true or false.

-->

<!ELEMENT required (#PCDATA)>

<!--

Specifies whether the security mechanism supports identity assertion or authorization attributes delivered in service context.

-->

<!ELEMENT sas-context (caller-propagation)>

<!--

The values of this element can be: required (SAP J2EE Engine accepts delegation tokens that indicate who has been endorsed to assert an identity and requires a delegation token that endorses SAP J2EE Engine as proxy for the client), supported (SAP J2EE Engine accepts delegation tokens that indicate who has been endorsed to assert an identity), and none (SAP J2EE Engine does not support identity assertion; the client identity will be obtained from the authentication layer(s).).

-->

<!ELEMENT caller-propagation (#PCDATA)>

<!--

Specifies information about the session beans in your application.

Example:

    <session-props>
        <property>
            <property-name>InitialSize</property-name>
            <property-value>0</property-value>
        </property>
        <property>
            <property-name>MaxSize</property-name>
            <property-value>1000</property-value>
        </property>
        <property>
            <property-name>ResizeStep</property-name>
            <property-value>1</property-value>
        </property>
        <property>
            <property-name>PoolClass</property-name>
            <property-value>
              com.sap.engine.services.ejb.util.pool.ContainerPoolImpl
            </property-value>
        </property>
    </session-props>
-->

<!ELEMENT session-props (session-timeout?, (passivation|keeps-open-resources)?, property*)>

<!--

The period (in seconds) since the session was last used, after which the EJB Container may destroy it. That is, the EJB Container performs the same operation as if the bean’s remove() method was invoked. The default session timeout is 36000 seconds. We recommend that the value of the session-timeout is longer than the expected duration of the methods; otherwise, this will lead to system errors. This property can be specified for stateful session beans only.

Example:
<session-timeout>36000</session-timeout>
-->

<!ELEMENT session-timeout (#PCDATA)>

<!--

Specifies whether the EJB Container passivates the bean instances. If this element is omitted in ejb-j2ee-engine.xml, the EJB Container will not passivate the bean instances. This property can be specified for stateful session beans only.

Example:
<passivation>
<passive-timeout>3600</passive-timeout>
<lrulimit>200</lrulimit>
</passivation>
-->

<!ELEMENT passivation (passive-timeout, lrulimit)>

<!--

The period (in seconds) since the bean’s passivation, after which the EJB Container clears the session bean’s instance from the swap and destroys the session. Any attempt to call a method from it will receive a system exception.

-->

<!ELEMENT passive-timeout (#PCDATA)>

<!--

The maximum number of active sessions in the EJB Container. Once this number is reached, the EJB Container passivates the session that was used least recently (LRU algorithm) and swaps its instance to the hard disk.

-->

<!ELEMENT lrulimit (#PCDATA)>

<!--

This element shows that the enterprise bean holds open resources. This means that the enterprise bean’s ejbPassivate() method must be executed before serializing the enterprise bean. This element is used only when the application is set to use failover.

-->

<!ELEMENT keeps-open-resources EMPTY>

<!--

Specifies information about the entity beans in your application.

-->

<!ELEMENT entity-props (unknown-pk-interval?, initial-cache-size?, property*)>

<!--

If a primary key is not defined for an entity bean, this specifies the interval for the values of the primary key. By default the EJB Container creates primary keys of type long for beans whose primary keys are not defined.

-->

<!ELEMENT unknown-pk-interval (#PCDATA)>

<!--

The initial size of the Persistence Manager cache. This property can be specified for container-managed entity beans only.

-->

<!ELEMENT initial-cache-size (#PCDATA)>

<!--

Specifies information about the message-driven beans in your application.

Example:

    <message-props>
        <destination-name>myDestination</destination-name>
        <connection-factory-name>myConnFactory</connection-factory-name>
        <property>
            <property-name>InitialSize</property-name>
            <property-value>0</property-value>
        </property>
        <property>
            <property-name>MaxSize</property-name>
            <property-value>1000</property-value>
        </property>
        <property>
            <property-name>ResizeStep</property-name>
            <property-value>1</property-value>
        </property>
        <property>
            <property-name>PoolClass</property-name>
            <property-value>
              com.sap.engine.services.ejb.message.SrvSessionPool
            </property-value>
        </property>
    </message-props>

-->

<!ELEMENT message-props (destination-name?, connection-factory-name?, property*)>

<!ELEMENT destination-name (#PCDATA)>

<!--

The name of the connection factory that will be used by the EJB Container to obtain connections in order to register the bean as a message listener.

-->

<!ELEMENT connection-factory-name (#PCDATA)>

<!--

Specifies the enterprise bean’s additional properties.

-->

<!ELEMENT property (property-name, property-value)>

<!--

The name of the property. Can be one of the following:

· InitialSize – the initial number of instances that will be created in the pool.

· MaxSize – the maximum number of instances that can exist in the pool.

· ResizeStep – the number, by which the total number of instances in the pool will be incremented each time a new instance is requested and there are no idle instances in the pool. The value of this element must be positive.

· PoolClass – the implementation class of the pool. The possible values for this property are: com.sap.engine.services.ejb.util.pool.ContainerPoolImpl (for stateless session and entity beans) and com.sap.engine.services.ejb.message.SrvSessionPool (for message-driven beans).

· stateful-failover – enables stateful failover for stateful session beans. The possible values for this property are true and false. For more information, see Structure link Failover for Enterprise Beans.

These properties can be set for stateless session beans, message-driven beans, and entity beans, whose containers use pools with instances.

-->

<!ELEMENT property-name (#PCDATA)>

<!--

The value of the specified property.

-->

<!ELEMENT property-value (#PCDATA)>

<!--

Specifies the isolation levels for the container-managed entity beans in the jar.

Example1:

    <transaction-descriptor>
      <isolation-level>
            <method>
                <ejb-name>myEJB</ejb-name>
                <method-intf>Remote</method-intf>
                <method-name>myMethod</method-name>
                <method-params>
                    <method-param>java.lang.String</method-param>
                    <method-param>java.lang.Integer</method-param>
                </method-params>
            </method>
            <isolation-attribute>Repeatable</isolation-attribute>
        </isolation-level>
    </transaction-descriptor>

Example2:

    <transaction-descriptor>
        <isolation-level>
            <ejb-name>myEJB</ejb-name>
            <isolation-attribute>Repeatable</isolation-attribute>
        </isolation-level>
    </transaction-descriptor>
-->

<!ELEMENT transaction-descriptor (isolation-level+)>

<!--

Sets isolation level for the entire enterprise bean, or for some of its methods.

-->

<!ELEMENT isolation-level ((method|ejb-name)+, isolation-attribute)>

<!--

Describes the method to which a transaction attribute will be set.

-->

<!ELEMENT method (ejb-name, method-intf?, method-name, method-params?)>

<!--

The interface in which the method is defined.

-->

<!ELEMENT method-intf (#PCDATA)>

<!--

The name of the method.

-->

<!ELEMENT method-name (#PCDATA)>

<!ELEMENT method-params (method-param*)>

<!--

The parameters of the method, if they are defined in the method.

-->

<!ELEMENT method-param (#PCDATA)>

<!--

The type of the isolation level – it can be ReadCommitted or Repeatable Read. The corresponding values for this element are Committed (for isolation level Read Committed) and Repeatable (for isolation level Repeatable Read). The default isolation level is Read Committed.

Example:

<isolation-attribute>Committed</isolation-attribute>

-->

<!ELEMENT isolation-attribute (#PCDATA)>

<!--

Contains a list of security role mappings to users or groups.

Example 1:

    <security-permission>
        <security-role-map>
            <role-name>Peter</role-name>
            <user-name>Administrator</user-name>
            <group-name>Administrators</group-name>
        </security-role-map>
    </security-permission>

Example 2:

    <security-permission>
        <security-role-map>
            <role-name>Jane</role-name>
            <server-role-name>Guest</server-role-name>
        </security-role-map>
    </security-permission>
-->

<!ELEMENT security-permission (security-role-map+)>

<!--

Maps security roles to existing server security roles. The mapping to users and groups is deprecated and should not be used.

-->

<!ELEMENT security-role-map (role-name, ((user-name*, group-name*) | server-role-name))>

<!--

The name of the security role that will be mapped.

-->

<!ELEMENT role-name (#PCDATA)>

<!--

A user that is already defined in the server environment and to which the security role will be mapped. Do not specify this element, its usage is deprecated.

-->

<!ELEMENT user-name (#PCDATA)>

<!--

A group that is already defined in the server environment and to which the security role will be mapped. Do not specify this element, its usage is deprecated.

-->

<!ELEMENT group-name (#PCDATA)>

<!--

A predefined security role in the root policy configuration of SAP J2EE Engine to which the current security role will be mapped.

-->

<!ELEMENT server-role-name (#PCDATA)>