Show TOC

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

Definition

This XML schema is optional unless you have to map specific resources used by the application to the ones already deployed on the system.

This document describes not only the elements of the XML schema, but also the specific MDB properties in the <bean-props> element.

Structure

The ejb-j2ee-engine_3_0.xsd has the following structure:

Figure 1: ejb-j2ee-engine.xsd

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, serv-component-ref

enterprise-beans

Describes the enterprise beans' deployment specifics.

Used in: ejb-j2ee-engine.

Contains: enterprise-bean.

enterprise-bean

Describes the enterprise beans' deployment specifics.

Used in: enterprise-beans.

Contains: ejb-name, jndi-name, ejb-ref, ejb-local-ref, resource-ref, resource-env-ref, message-destination-ref, server-component-ref, ior-security-config, bean-props.

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.

Caution

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 prefix in the arbitrary JNDI name of your bean, this prefix must not coincide with the name of another object bound in the JNDI namespace.

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.

ejb-ref
Caution

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

    <ejb-ref>
        <ejb-ref-name>myEJBRef</ejb-ref-name>
        <jndi-name>ReferencedEJBJNDIName</jndi-name>
    </ejb-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-ref.

jndi-name

Specifies the JNDI name of the referenced bean.

Used in: ejb-ref.

ejb-local-ref
Caution

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.

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 .

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

    <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: res-env-ref-name, jndi-name.

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

message-destination-ref

Creates a reference to a message destination.

Used in: enterprise-bean.

Contains: message-destination-ref-name, jndi-name.

message-destination-ref-name

The name of the destination.

Used in: message-destination-ref.

jndi-name

The JNDI name of the destination.

Used in: message-destination-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: name, jndi-name.

name

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

Used in: server-component-ref.

jndi-name

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

Used in: server-component-ref.

ior-security-config

Specifies the security mechanisms that are supported by the AS Java 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.

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.

  • 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 will be 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.

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

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

  • 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 will be 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 will not be used; authentication using transport level(s) or identity assertion will be 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 the proxy for the client.

  • supported - the AS Java accepts delegation tokens that indicate who has been endorsed to assert an identity.

  • none - the AS Java does not support identity assertion; the client identity will be obtained from the authentication layer(s).

Used in: sas-context.

bean-props

The properties of the bean.

Used in: enterprise-bean.

Contains: SAP predefined MDB properties and session timeout properties.

property

Specifies the enterprise bean's additional properties.

Used in: bean-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 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 (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 when requested (no matter if the MaxSize is reached), the BlockingContainerPoolImpl will wait until an instance is released and thus ensures that the number of instances in the pool will never exceed the value of the MaxSize property.

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 as their instances are not kept in pools.

Message-Driven Beans Specific Properties

  • single-server-node

    This property can be specified both for message-driven beans subscribed to a destination of type Queue and Topic. Possible values: true and false. If set to true, the message-driven bean will be activated on exactly one cluster node.

  • 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 recreate 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 recreate an inactive JMS connection. The default value is 1000.

Example

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.

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, server-role-name.

role-name

The name of the security role that will be mapped.

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

app-startup-method

Specifies that an EJB Startup Hook is attached to the corresponding business method.

Used in: enterprise-bean.

Contains: method.

app-shutdown-method

Specifies that an EJB Shutdown Hook is attached to the corresponding business method.

Used in: enterprise-bean.

Contains: method.

method

The name of the method that is related to an EJB Startup or Shutdown Hook.

More information: Binding the Life Cycle of Application and Business Components

Used in: app-startup-method, app-shutdown-method.

MDB Properties in <bean-props>

Element

Default Value

Description

single-server-node

False

This property is applicable only in a cluster environment. It specifies whether to register the endpoint on each server node in the cluster or only once. For example in case of JMS destination Topic, activating the endpoint on each server node would mean that each JMS message will be received by the message-driven bean on each server node which could break the application logic. Setting the property 'single-server-node' to 'true' will ensure that the message will be received only once in the cluster. This property could be also applicable for other ResourceAdapters except SAP JMS ResourceAdapter. Please note that setting the property to 'true' does not mean that the application will be started on only one server node. The application will be shown as started in the whole cluster but only one of the server nodes will be operational. If this server node is shutdown by some reason, another one will be randomly chosen. It is also not possible to specify on which server node to activate the endpoint.

stateful-mdb

False

If set to 'true', there will be a one-to-one mapping between the endpoint and a bean instance. This means that each call to the same endpoint instance will be delegated to one and the same bean instance. The association is broken when the endpoint is released (i.e. its release() method is called by the ResourceAdapter). The default behavior is that the endpoint and the bean instance are loosly-coupled, i.e. an arbitrary bean instance is taken from the pool on each endpoint method invocation. Setting this property to 'true' would mean that the ResourceAdapter can rely on the state kept in the message-driven bean instance between different messages processing.

resource-adapter-name

"!SAP_JMS_RA!"

Specifies the name of the ResourceAdapter to register the endpoint to. If not specified, the message-driven bean is registered in all available ResourceAdapters which supports the given messaging type. In case of messaging type javax.jms.MessageListener, the default name of the ResourceAdapter is "!SAP_JMS_RA!", which is the name of the SAP JMS ResourceAdapter.

reconnect-attempts

1

Specifies the number of attempts to activate an endpoint. This could be helpful if the ResourceAdapter or the EIS system at the backend is not fully operational during MDB application startup. This property is also used in case the 'single-server-node' property is set to 'true' and the server node where the endpoint is registered shuts down. In such a case, when the SAP JMS ResourceAdapter is used, it is possible that the so called SAP JMS lock-owner is also restarting at the moment and it might take some time until it is fully operational. This property might be also applicable in case of other ResourceAdapters.

sleep-between-attempts

0

Specifies the interval (in milliseconds) between two consecutive attempts to activate an endpoint.