Show TOC

ejb-j2ee-engine.xsdLocate this document in the navigation structure

Definition

An XML schema 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 schema 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.xsd has the following structure:

Schema Element / Attribute

Description

ejb-j2ee-engine

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

description

Description of the contents of this XML.

Used in: ejb-j2ee-engine

 

enterprise-beans

Describes enterprise beans' deployment specifics.

Used in: ejb-j2ee-engine

Contains: enterprise-bean

 
 

enterprise-bean

The enterprise bean.

Used in: enterprise-beans

Contains: ejb-name , jndi-name , container-size , ejb-ref , ejb-local-ref , resource-ref , resource-env-ref , message-destination-ref , server-component-ref , run-as-identity-map , ior-security-config

 
 

ejb-name

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.

Used in: enterprise-bean

 

jndi-name

An arbitrary JNDI name for the bean.

We recommend that you do not specify or use this arbitrary JNDI name because the JNDI name that you specify must be unique within all other beans and objects bound in the JNDI namespace of the AS Java, and name conflicts may occur. Also, if you specify a

Instead of specifying this arbitrary JNDI name, we recommend that you declare EJB references and use them to access your beans (when the client application is a Java EE application) or you use the default JNDI name of the bean to look up it (when the client application is not a Java EE application).

Used in: enterprise-bean

 
 
 

container-size

Deprecated.

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

Used in: enterprise-bean

 
 

ejb-ref

Note

Use this element only if the information in the corresponding <ejb-ref> element in the ejb-jar.xml is not sufficient to identify the referenced bean (for example, when there is more than one enterprise bean with the same remote interfaces deployed on the AS Java).

This element additionally defines a remote EJB reference that the referring bean has to another enterprise bean (by specifying the JNDI name of the referenced enterprise bean). This remote EJB reference must be defined first in an <ejb-ref> element in ejb-jar.xml .

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

                           

Used in: enterprise-bean , ejb-local-ref

Contains: ejb-ref-name , jndi-name

 
 
 
 
 
 
 
 
 

ejb-ref-name

The name of the EJB reference as defined in ejb-jar.xml . The value of this element must be the same as the value of the corresponding <ejb-ref-name> element in ejb-jar.xml .

Used in: ejb-ref

 

jndi-name

Specifies the JNDI name of the referenced bean.

Used in: ejb-ref

ejb-local-ref

Note

Use this element only if the information in the corresponding <ejb-local-ref> element in the ejb-jar.xml is not sufficient to identify the referenced bean (for example, when there is more than one enterprise bean with the same local interfaces deployed on the AS Java).

This element additionally defines a local EJB reference that the referring bean has to another enterprise bean (by specifying the JNDI name of the referenced enterprise bean). This local EJB reference must be defined first in an <ejb-local-ref> element in ejb-jar.xml .

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

                        

Used in: enterprise-bean

Contains: ejb-ref-name , jndi-name

 
 
 
 
 
 
 
 
 

ejb-ref-name

The name of the EJB reference as defined in ejb-jar.xml . The value of this element must be the same as the value of the corresponding <ejb-ref-name> element in ejb-jar.xml .

Used in: ejb-local-ref

Used in: ejb-local-ref

jndi-name

Specifies the JNDI name of the referenced bean.

Used in: ejb-local-ref

 

resource-ref

Additionally defines an enterprise bean's reference to an external resource (by specifying the JNDI name of the referenced resource and/or defining the resource as non-transactional). This reference must be defined first in the ejb-jar.xml .

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

                           

Used in: enterprise-bean

Contains: res-ref-name , res-link , non-transactional

 
 
 
 
 
 
 
 

res-ref-name

The name of the resource manager connection factory reference as defined in ejb-jar.xml. The value of this element must be the same as the value of the corresponding <res-ref-name> element in ejb-jar.xml

Used in: resource-ref.

 

res-link

Specifies the JNDI name of the referenced resource.

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

Used in: resource-ref

 
 
 
 
 

non-transactional

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

Used in: resource-ref

 

resource-env-ref

Additionally defines an enterprise bean's reference to an administered object associated with a resource in the bean's environment (by specifying the JNDI name of the resource environment reference). This reference must be defined first in the ejb-jar.xml .

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

                           

Used in: enterprise-bean

Contains: resource-env-ref-name , jndi-name

 
 
 
 
 
 
 

resource-env-ref-name

The name of the resource environment reference as defined in ejb-jar.xml . The value of this element must be the same as the value of the corresponding <resource-env-ref-name> element in ejb-jar.xml .

Used in: resource-env-ref

 

jndi-name

Specifies the JNDI name of the resource environment reference.

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.

Used in: resource-env-ref

 
 

server-component-ref

Specifies a reference from the EJB application to the AS Java interface or to service objects bound in the JNDI namespace. To be able to look up the specified object, apart from this reference, you must also declare a reference to the corresponding AS Java service or interface in the <reference> element in the application's application-j2ee-engine.xml .

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

                        

Used in: enterprise-bean

Contains: description , name , type , jndi-name

 
 
 
 
 
 
 
 
 

description

Description of the server component reference.

Used in: server-component-ref

 

name

The name with which the resource is looked up. This name is relative to the java:comp/env context.

Used in: server-component-ref

 

type

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

Used in: server-component-ref

 

jndi-name

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

Used in: server-component-ref

 

run-as-identity-map

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

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

                           

Used in: enterprise-bean

Contains: user-name

 
 
 
 
 
 

user-name

The name of the user to use for run as identity.

Used in: run-as-identity-map

 

ior-security-config

Specifies the security mechanisms that are supported by the AS Java when a lookup using IIOP is performed. These mechanisms are used according to Conformance Level 0 defined in the OMG's Common Secure Interoperability V2 Specification.

Used in: enterprise-bean

Contains: transport-config , as-context , sas-context

 
 

transport-config

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

Used in: ior-security-config

Contains: integrity , confidentiality , establish-trust-in-target , establish-trust-in-client

 
 

integrity

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

Used in: transport-config

 

confidentiality

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

Used in: transport-config

 

establish-trust-in-target

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

Used in: transport-config

 

establish-trust-in-client

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

Used in: transport-config

 

as-context

Describes the authentication context.

Used in: ior-security-config

Contains: auth-method , realm , required

 
 

auth-method

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

Used in: as-context

 

realm

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

Used in: as-context

 

required

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

Used in: as-context

 

sas-context

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

Used in: ior-security-config

Contains: caller-propagation

 
 

caller-propagation

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

Used in: sas-context

 

session-props

Specifies information about the session beans in your application.

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

                        

Used in: enterprise-bean

Contains: session-timeout , property

 
 

session-timeout

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 has been 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 leads to system errors. This property can be specified for stateful session beans only.

<session-timeout>36000</session-timeout>
                        

Used in: session-props

 
 
 

entity-props

Specifies information about the entity beans in your application.

Used in: enterprise-bean

Contains: unknown-pk-interval , initial-cache-size , property

 
 

unknown-pk-interval

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.

Used in: entity-props

 

initial-cache-size

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

Used in: entity-props

 

message-props

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

<message-props>
        <destination-name>myTopic</destination-name>
        <connection-factory-name>myTopicFactory</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.util.pool.BlockingContainerPoolImpl</property-value>
        </property>
        <property>
                <property-name>topic-on-all-nodes</property-name>
                <property-value>true</property-value>
        </property>
        <property>
                <property-name>reconnect-attempts</property-name>
                <property-value>50</property-value>
        </property>
        <property>
                <property-name>sleep-between-attempts</property-name>
                <property-value>45000</property-value>
        </property>
</message-props>

                        

Used in: enterprise-bean

Contains: destination-name , connection-factory-name , property

 
 

destination-name

The name of the Topic or the Queue destination to which the bean wants to be subscribed.

Used in: message-props

 

connection-factory-name

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

Used in: message-props

 

property

Specifies the enterprise bean's additional properties.

Used in: message-props

Contains: property-name , property-value

 
 

property-name

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

Pool Properties

  • InitialSize

    The initial number of instances that is 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 is 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 (the default one),

    • com.sap.engine.services.ejb.util.pool.BlockingContainerPoolImpl

    Your own implementation that is a subclass of com.sap.engine.services.ejb.util.pool.ContainerPoolImpl .

If you change the default PoolClass from ContainerPoolImpl to BlockingContainerPoolImpl , this affects the pool behavior when a new instance is requested and there are no idle instances in the pool. Whereas ContainerPoolImpl creates new instances each time

Note

The InitialSize , MaxSize , ResizeStep , and PoolClass properties can be set for stateless session beans, message-driven beans, and entity beans because their containers use pools with instances. These properties are not available for stateful session beans

Message-Driven Beans Specific Properties

  • topic-on-all-nodes

    This property can only be specified for message-driven beans subscribed to a destination of type Topic. Possible values: true and false. If set to true, the message-driven bean is activated on each server process in the cluster. Thus, each message is received on each server process. This functionality can be used by the application for cluster communication for example. By default, the value of this property is false , that is, only one connection consumer is registered for the application, thus ensuring that each message isreceived only once by the same message-driven bean.

  • reconnect-attempts

    In case the container receives a notification by the JMS system that a connection is not active any more, this property specifies the number of attempts the EJB Container performs to re-create the JMS connection. The default value is 10 . The interval between two consecutive attempts is determined by the sleep-between-attempts property.

  • sleep-between-attempts

    Specifies the interval (in milliseconds) between two consecutive attempts of the EJB Container to re-create an inactive JMS connection. The default value is 1000 .

Recommendation

The default values of the reconnect-attempts and sleep-between-attempts properties are considered optimal for a typical message-driven beans scenario, and enough for the JMS system to recover from a server process failure. We recommend that you modify these values only in case of complicated scenarios (for example, involving more than one cluster).

Used in: property

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

property-value

The value of the specified property.

Used in: property

 

transaction-descriptor

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

Sample Code
<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>

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

                           

Used in: ejb-j2ee-engine

Contains: isolation-level

 
 

isolation-level

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

Used in: transaction-descriptor

Contains: method , ejb-name , isolation-attribute

 
 

method

Describes the method to which a transaction attribute is set.

Used in: isolation-level

Contains: ejb-name , method-intf , method-name , method-params

 
 

ejb-name

The name of the EJB.

Used in: method , isolation-level

 

method-intf

The interface in which the method is defined.

Used in: method

 

method-name

The name of the method.

Used in: method

 

method-params

Used in: method

Contains: method-param

 

method-param

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

Used in: method-params

 

isolation-attribute

The type of the isolation level. This can be Read Committed 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.

Sample Code
<isolation-attribute>Committed</isolation-attribute>
                           

Used in: isolation-level

 

security-permission

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

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

                        

Used in: ejb-j2ee-engine

Contains: security-role-map

 
 

security-role-map

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

Used in: security-permission

Contains: role-name , user-name , group-name

 
 

role-name

The name of the security role that is mapped.

Used in: security-role-map

 

user-name

Deprecated.

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

Used in: security-role-map

 
 

group-name

Deprecated.

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

Used in: security-role-map

 
 

server-role-name

A predefined security role in the root policy configuration of the AS Java to which the current security role is mapped.

Used in: security-role-map

 

message-destination-maps

Creates mapping to a real destination. A link is created between the message destination and the resource deployed on the AS Java.

Used in: ejb-j2ee-engine

Contains: message-destination

 
 

message-destination

Defines a message destination.

Used in: message-destination-maps

Contains: message-destination-name , jndi-name

 
 

message-destination-name

The name of the destination.

Used in: message-destination

 

jndi-name

The JNDI name associated with the destination. The name with which the resource is deployed.

Used in: message-destination