EJB-module deployment

This article explains how to deploy an EJB-module to the Orion Application Server.

1 Introduction

    This article provides a step-by-step guide to deploying an existing EJB-module to an Orion Application Server. It also gives a brief overview of the structure of a EJB-module. Information about deploying a full J2EE application can be found in the Application Deployment article.

2 The structure of a EJB-module in brief

    This section briefly describes the structure of a J2EE EJB-module.

    A J2EE EJB-module is one of the J2EE Module types that are parts of a J2EE Application (others are Web-modules, Client-modules and Connector-modules).

    An EJB-module might be part of a J2EE application as described in the Application Deployment document.

    An EJB-module typically consists of classes and a EJB-module descriptor describing the EJB-module. This is normally packaged into a .jar file but doesn't have to be.

    Classes such as EJBs, beans, helper-classes and others are placed under the root of a EJB-module.

    If the EJB-module is using other JAR archives, the manifest file of the EJB-module should contain a class-path containing the path to these JAR archives.

    Regardless of if the EJB-module is packaged or not, the file structure should look something like in the following example:


        /com/acme/ejb/companyEJB.class
        /com/acme/ejb/companyHome.class
        /com/acme/ejb/company.class
        /com/other/ejb/companyHelper.class
        /META-INF/ejb-jar.xml
        /META-INF/MANIFEST.MF
    Listing 1: EJB-module file structure example

    Using an unpackaged directory structure is very effective during development.

    As this article is about deploying EJB-modules and not about creating them, the structure of EJB-modules will not be further explored here.

3 Deploying a standalone EJB-module manually

    If the EJB-module to deploy is not part of a J2EE application, the following steps can be followed to add it to the default application shipped with Orion:

    3.1 Step 1: Add the EJB-module to the default Application

      Add an entry like the one given below to the orion-application.xml file of the Server you are deploying to: 


          <ejb-module
              path="../applications/name.jar"
              remote="true"
          />
      Listing 2: Adding a EJB entry to /orion/config/application.xml

      The syntax of the EJB-module tag can be found here.

      Replace the value of the path attribute with the path to the EJB-module, either to the .jar file or the root directory of an unpackaged EJB-module (the directory holding the EJB-modules META-INF directory).

      Replace the value of the remote attribute with either "true" or "false", with "false" being the default and "true" implying that this EJB-module should be run from a remote Orion Application Server where it has previously been deployed. More information about remote EJB-modules can be found in the Remote Access article.

4 Deployment configuration

    After an EJB-module has been deployed (standalone or as part of a J2EE application), it is possible to modify its configuration by editing the generated orion-ejb-jar.xml file. This file is normally located in the EJB-modules directory within the deployment directory of the Application that the EJB-module is part of (The default Application when adding standalone EJB-modules). 


                        /orion/application-deployments/default/EJB-module name/orion-ejb-jar.xml
    Listing 3: Location of the deployment configuration file if the EJB-module was added to the default Application. Notice that "EJB-module name" should be replaced with the actual name of the EJB-module (including the .jar suffix if was a packaged archive).

    Deployment configurations can be distributed with the EJB-module by placing the orion-ejb-jar-xml file within the META-INF directory (next to the ejb-jar.xml file) of the EJB-module. The container will then use the distributed deployment configuration file as base when deploying the EJB-module for the first time. When re-deploying the EJB-module the deployment configuration file of the EJB-module's deployment directory will be used as the base.

    The settings available for deployment configuration of an EJB-module are:

    4.1 Configuring copy-by-value behaviour

      By default, Orion clones all incoming/outgoing parameters in EJB calls. Set this to 'false' if the Application does not rely on copy-by-value semantics for an increase in speed.


      <orion-ejb-jar>
          <enterprise-beans>
              <session-deployment
                  name="myBean"
                  copy-by-value="false"
              />
          </enterprise-beans>
      </orion-ejb-jar>
      Listing 4: Disabling cloning of incoming/outgoing parameters for a SessionBean


      <orion-ejb-jar>
          <enterprise-beans>
              <entity-deployment
                  name="myBean"
                  copy-by-value="false"
              />
          </enterprise-beans>
      </orion-ejb-jar>
      Listing 5: Disabling cloning of incoming/outgoing parameters for an EntityBean

      By setting the value of the copy-by-value attribute to "false", Orion will not clone incoming/outgoing parameters. The default value is "true". To understand the impact of the value of the copy-by-value attribute consider the following scenario:


          The SessionBean MySessionEJB holds a List of Integers (1,2,3), which is available through the
              List getList()
          method. A JSP page is performing the following operation:
              List entries=mySession.getList();
              ArrayList single=new ArrayList();
              single.add(new Integer(1));
              entries.retainAll(single);
              System.out.println(mySession.getList().size());
      Listing 6: Sample scenario description

      If the SessionBean mentioned above has a deployment configuration entry containing the value "true" for the copy-by-value attribute, the above operation would not affect the List held by the SessionBean. The output would report that the List would still contain 3 objects

      If, on the other hand, the value were "false" for the copy-by-value attribute, the above operation would affect the List held by the SessionBean and the output would report that the List now would contain 1 object.

    4.2 Configuring IIOP exposure

      By default an EJB is not exposed via IIOP. To expose an EJB via IIOP, add an entry like shown in listing 7 and 8 below to the EJB-modules orion-ejb-jar-xml file:


      <orion-ejb-jar>
          <enterprise-beans>
              <session-deployment
                  name="myBean"
                  iiop-accessable ="true"
              />
          </enterprise-beans>
      </orion-ejb-jar>
      Listing 7: Exposing a SessionBean for IIOP access


      <orion-ejb-jar>
          <enterprise-beans>
              <entity-deployment
                  name="myBean"
                  iiop-accessable ="true"
              />
          </enterprise-beans>
      </orion-ejb-jar>
      Listing 8: Exposing an EntityBean for IIOP access

      Where the value of the iiop-accessable attribute is a boolean attribute that should be set to "true" if the EJB should be available via IIOP. The default is "false".

      The entry in listing 7 or 8 above would expose the EJB at "iiop://[server]/[application-name]/[location]", where server would be the hostname/ip the Server is running on, application-name would be the deployment name of the Application (as configured in the deployment setting in the Servers server.xml) and location would be the JNDI-name the EJB is bound to.

      In order for any EJB to be exposed via IIOP, the Server needs to have an ORB instance configured in its server.xml.

    4.3 Configuring the JNDI-location

      By default, Orion binds the EJB to a JNDI location matching the value of the EJBs name attribute. The JNDI-location is specified in the location attribute of the EJBs deployment tag as exemplified in listing 9 and 10 below:


      <orion-ejb-jar>
          <enterprise-beans>
              <session-deployment
                  name="myBean"
                  location ="myBean"
              />
          </enterprise-beans>
      </orion-ejb-jar>
      Listing 9: Binding a SessionBean to a certain JNDI location


      <orion-ejb-jar>
          <enterprise-beans>
              <entity-deployment
                  name="myBean"
                  location ="myBean"
              />
          </enterprise-beans>
      </orion-ejb-jar>
      Listing 10: Binding a EntityBean to a certain JNDI location

      Where the value of the location attribute would be the JNDI location for the EJB to be bound to.

      The entry in listing 9 and 10 above would expose the EJB with a Remote interface at "ormi://[server]/[application-name]/[location]", where server would be the hostname/ip the Server is running on, application-name would be the deployment name of the Application (as configured in the deployment setting in the Servers server.xml) and location would be the JNDI location the EJB is bound to. Notice that local EJBs does not get exposed. For local EJBs, the value of the location attribute will only be used to reference the EJB in the Orion specific deployment configurations.

    4.4 Configuring SessionBean persistence filename

      Orion uses the configured persistence-filename attribute to preserve the SessionBeans state over Server restarts in the persistence directory of the Application. By default, Orion uses the name of the SessionBean as the filename.


      <orion-ejb-jar>
          <enterprise-beans>
              <session-deployment
                  name="myBean"
                  persistence-filename="myBean"
              />
          </enterprise-beans>
      </orion-ejb-jar>
      Listing 11: Configuring the SessionBean's persistence filename.

      Where the value of the persistence-filename will be used as filename when preserving the SessionBeans state over Server restarts.

    4.5 Configuring deployment values for references and entries

      4.5.1 Configuring environment entries

        To override the value of a certain environment entry with a deployment specific value, add an entry like shown in listing 12,13 and 14 below to the EJB's entry in the EJB-module's orion-ejb-jar.xml file.


        <orion-ejb-jar>
            <enterprise-beans>
                <session-deployment
                    name="myBean">
                    <env-entry-mapping name="theName">deploymentValue</env-entry-mapping>
                </session-deployment>
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 12: Overriding environment entries for a SessionBean.


        <orion-ejb-jar>
            <enterprise-beans>
                <entity-deployment
                    name="myBean">
                    <env-entry-mapping name="theName">deploymentValue</env-entry-mapping>
                </entity-deployment>
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 13: Overriding environment entries for an EntityBean


        <orion-ejb-jar>
            <enterprise-beans>
                <message-driven-deployment
                    name="myBean">
                    <env-entry-mapping name="theName">deploymentValue</env-entry-mapping>
                </message-driven-deployment>
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 14: Overriding environment entries for a MessageDrivenBean

        Where the name attribute of the env-entry tag holds the name of the environment entry to override, and the body of the env-entry-mapping tag holds the new value that should be given to the named environment entry.

      4.5.2 Configuring EJB references

        An EJB uses JNDI to lookup EJBs. These JNDI names need to be mapped to an actual JNDI locations of EJBs with home/remote interfaces (local-home/local for Locals) matching the specified home/remote (local-home/local for Locals) interfaces of the ejb-reference. By default, Orion maps the ejb-reference to the first encountered EJB that matches the home/remote (or local-home/local) interfaces specified in the ejb-reference tag. As multiple EJBs might be using the same home/remote (or local-home/local) interfaces, it is sometimes necessary to manually configure the mapping between the ejb-reference and the actual EJB. This is done through entries like the one shown in listing 15,16 and 17 below.


        <orion-ejb-jar>
            <enterprise-beans>
                <session-deployment
                    name="myBean">
                    <ejb-ref-mapping location="ejb/thePayroll" name="ejb/myPayroll"/>
                </session-deployment>
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 15: Mapping a SessionBeans ejb-reference to the location of an EJB.


        <orion-ejb-jar>
            <enterprise-beans>
                <entity-deployment
                    name="myBean">
                    <ejb-ref-mapping location="ejb/thePayroll" name="ejb/myPayroll"/>
                </entity-deployment>
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 16: Mapping an EntityBeans ejb-reference to the location of an EJB.


        <orion-ejb-jar>
            <enterprise-beans>
                <message-driven-deployment
                    name="myBean">
                    <ejb-ref-mapping location="ejb/thePayroll" name="ejb/myPayroll"/>
                </message-driven-deployment>
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 17: Mapping a MessageDrivenBean's ejb-reference to the location of an EJB.

        Where the value of the name attribute would be the name used by the EJB to reference the other EJB. The value of the location would be the JNDI location of the actual EJB (and match the location value for the EJBs entry in its EJB-mobules orion-ejb-jar.xml file).


        ...
        Context context=new InitialContext();
        LocalPayRollHome payroll=(LocalPayRollHome)context.lookup("java:comp/env/ejb/myPayroll");
        ...
        Listing 18: Example of looking up an EJB from another EJB.

      4.5.3 Configuring resource reference mappings

        An EJB uses JNDI to lookup resources in its context. These JNDI names need to be mapped to an actual resource JNDI location. By default, Orion maps the default resource of the specified type to the resource reference of the EJB. As an example, any DataSource resource references the EJB has would be mapped to the first configured DataSource available. In order to change this behaviour, add an entry like the one shown in listing 19,20 and 21 below to the EJB's entry in the EJB-modules orion-ejb-jar.xml file:


        <orion-ejb-jar>
            <enterprise-beans>
                <session-deployment
                    name="myBean">
                    <resource-ref-mapping location="jdbc/HyperSonicDS" name="jdbc/myDS"/>
                </session-deployment>
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 19: Mapping a SessionBean's resource reference to a resource


        <orion-ejb-jar>
            <enterprise-beans>
                <entity-deployment
                    name="myBean">
                    <resource-ref-mapping location="jdbc/HyperSonicDS" name="jdbc/myDS"/>
                </entity-deployment>
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 20: Mapping an EntityBean's resource reference to a resource


        <orion-ejb-jar>
            <enterprise-beans>
                <message-driven-deployment
                    name="myBean">
                    <resource-ref-mapping location="jdbc/HyperSonicDS" name="jdbc/myDS"/>
                </message-driven-deployment>
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 21: Mapping a MessageDrivenBean's resource reference to a resource

        Where the value of the location attribute would be the JNDI location of the previously defined resource and map this to the name specified in the name attribute.


        ...
        Context context=new InitialContext();
        DataSource ds=(DataSource)context.lookup("java:comp/env/jdbc/myDS");
        ...
        Listing 22: Example of looking up a DataSource from within a EJB

        If the resource needs to be looked up from another context than the default one, such as when using a external third party resource, an entry like the one describe in listing 23 below can be used:


        <orion-ejb-jar>
            <enterprise-beans>
                <entity-deployment
                    name="myBean">
                    <resource-ref-mapping location="jdbc/HyperSonicDS" name="jdbc/myDS">
                        <lookup-context location="foreign/resource/location">
                            <context-attribute name="java.naming.factory.initial" value="classname" />
                            <context-attribute name="name" value="value" />
                        </lookup-context>
                    </resource-ref-mapping>
                </entity-deployment>
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 23: Specifying the context to use when looking up the resource. The same syntax can be used by SessionBeans or MessageDrivenBeans.

        Where the value of the location attribute would be the name used to lookup the resource in the foreign context.

        Additional context attributes can be specified by using the context-attribute tag where the name attribute holds the name and the value attribute holds the value for each name-value pair.

        Please notice that the context attribute named "java.naming.factory.initial" is an obligatory attribute that should have the context factory class as its value.

    4.6 Configuring caching

      4.6.1 Configuring Entitybean cache handling

        In order to increase performance, Orion keeps a cache of unassigned instances as well as a cache of assigned instances.

        When a Entitybean is accessed Orion will first look for a instance with the sought for identity in the "ready" pool. If no such instance is found, Orion will reuse any unassigned instance found in the "pooled" cache which is then given an identity as it is moved into it "ready" state and is made ready to serve the client.

        A new Entitybean would be moved into the "ready" cache when its ejbPostCreate() method is completed. An existing Entitybean would be moved into the "ready" cache when its ejbActivate() method is completed.

        By specifying a validity-timeout period for the Entitybean, the container can make sure to refresh an entity periodically. This is useful when external resources are periodically updating the underlying data.


        Figure 1: This simplified UML statechart describes how an instance moves between its "pooled" and "ready" state, as well as how the ejbLoad() method is called whenever the Entity's validity-timeout setting is exceeded.

        After that an Entitybean has been used, it will be kept in the "ready" cache for a certain amount of time (the timeout value), after which it will be moved into the "pooled" cache, thereby loosing its identity and becoming an unassigned instance.

        Unassigned instances are kept in the "pooled" cache until any specified timeout value is exceeded, when it will be removed from the cache.

        By default, Orion allows for an infinite number of instances to be held in cache. This behaviour can be overridden by specifying a maximum number of instances to be held in cache.

        When a client accesses existing Entitybean, Orion will check the "ready" pool for an instance with the sought for identity. If none is found, Orion will take any unassigned instance from the "pooled" cache and give it an identity instead.

        4.6.1.1 Configuring the minimum time to keep an assigned instance in cache

          By default, Orion keeps entities in its "ready" state (assigned to an identity) for a minimum of 60 seconds after their last usage. If there is no activity during the specified period the entity may be passivated into its "pooled" state (not assigned to an identity).

          To change the default behaviour, add an entry like shown in listing 24 below to the orion-ejb-jar.xml of the EJB-module:


          <orion-ejb-jar>
              <enterprise-beans>
                  <enity-deployment
                      name="myBean"
                      instance-cache-timeout="120"
              </enterprise-beans>
          </orion-ejb-jar>
          Listing 24: Configuring the minimum time to keep an unused entity in its "ready" state

          Where the value of the instance-cache-timeout attribute is the minimum number of seconds to wait before the entity should be passivated into its "pooled" state or "never" to keep the entity in its "ready" state forever.

          Never passivating entities will give a performance boost but will have a major impact on memory usage.

        4.6.1.2 Configuring the minimum time to keep an unassigned entity in cache

          By default, Orion keeps entities in its "pooled" state (not assigned to an identity) for a minimum of 60 seconds after their last usage. If there is no activity during the specified period the instance may be removed from cache.

          To change the default behaviour, add an entry like shown in listing 25 below to the orion-ejb-jar.xml of the EJB-module:


              <orion-ejb-jar>
                  <enterprise-beans>
                      <enity-deployment
                          name="myBean"
                          pool-cache-timeout="120"
                  </enterprise-beans>
              </orion-ejb-jar>
          Listing 25: Configuring the minimum time to keep an entity in its "pooled" state

          Where the value of the pool-cache-timeout attribute is the minimum number of seconds to wait before the instance should be removed or "never" to keep the instance in its "ready" state forever.

          Never removing instances will give a performance boost but will have a major impact on memory usage.

        4.6.1.3 Configuring refresh-interval for pooled Entities

          By default, Orion assumes that the data held by the pooled instances are valid until the instance is passivated or removed. The validity-timeout setting forces Orion to refresh instances at the give interval

        4.6.1.4 Configuring the maximum number of cached instances

          By default, Orion allows for an infinite number of Entity instances to be kept in its "ready" or "pooled" state until they are reused or removed due to timeout settings. To change this behaviour, add an entry like the one shown in listing 26 below to the orion-ejb-jar.xml file of the EJB-module:


              <orion-ejb-jar>
                  <enterprise-beans>
                      <enity-deployment
                          name="myBean"
                          max-instances="90"
                  </enterprise-beans>
              </orion-ejb-jar>
          Listing 26: Configuring maimum number of instances for an Entity.

          Where the value of the max-instances attribute is the maximum number of instances to be kept in its "ready" or "pooled" state.

          Please notice that the total number of instances might exceed this setting when a large amount of instances are used. The total number will go below the configured max-instance value as soon as these instances are no longer used.

      4.6.2 Configuring Sessionbean cache handling

        4.6.2.1 Configuring Stateless Sessionbean cache timeout

          When a client calls a method on a Stateless Sessionbean, Orion looks in the pool for a currently unused instance (method-ready) of the Sessionbean to give to the client. If no instance is free to serve the client, Orion will create a new Instance, call its setSessionContext() Method, call its ejbCreate() method and finally add it to the pool of method-ready instances.

          The clients call to the create() method of the EJB has no correlation with when Orion adds instances to the method-ready pool. Orion will add new instances as seemed fit.


          Figure 2: UML statechart describing the simplified lifecycle of a stateless Sessionbean.

          After that the specified cache-timeout period is exceeded, Orion will timeout the Sessionbean instance by calling its ejbRemove() method and thereby removing it from the method-ready pool.

          By default, Orion keeps Stateless Sessionbeans in the method-ready pool for a minimum of 60 seconds after their last usage. To change this behaviour, add an entry like shown in listing 27 below to the orion-ejb-jar.xml file of the EJB-module.


          <orion-ejb-jar>
              <enterprise-beans>
                  <session-deployment
                      name="myBean"
                      cache-timeout="30"
                  />
              </enterprise-beans>
          </orion-ejb-jar>
          Listing 27: Configuring the Stateless Sessionbean cache timeout period

          In the example above, the Stateless Sessionbean with the name myBean (the value of the name attribute should be the name of the EJB in the EJB-module's ejb-jar.xml file) has been configured to be held in the method-ready pool for atleast 30 seconds after that it was last used. The default value of the cache-timeout attribute is "60" .

          If the Stateless Sessionbean should never timeout, the cache-timeout should be given a value of "never".

        4.6.2.2 Configuring Stateful Sessionbean cache timeout

          When a client calls a create method on the Stateful Sessionbean, Orion will create a new instance of the Sessionbean, call its setSessionContext() and finally its ejbCreate() method. After this, the Sessionbean instance is in its method-ready state and can be used by the client.


          Figure 3: UML statechart describing the simplified lifecycle of a stateful Sessionbean.

          At a certain time, Orion might decide that the Sessionbean should be passivated and call its ejbPassivate() method and thereafter passivate its state to a secondary storage. After this, the Sessionbean is in its passive state. If the client would try to utilize the Sessionbean again, Orion would activate it by reloading the SessionBeans state from secondary storage and calling its ejbActivate() method, where after the SessionBean would be in its method-ready state again.

          Sometimes after a minimum period of passivity equal to the number of seconds configured in the timeout attribute for the SessionBean, Orion would remove the Sessionbean from the cache. If the client would try to utilize the Sessionbean, Orion would throw a java.rmi.NoSuchObjectException (for a remote client) or a javax.ejb.NoSuchObjectLocalException (for a local client).

          By default, Orion keeps passive stateful Sessionbeans for 30 minutes before letting them timeout. To change this behaviour, add an entry like the one shown in listing 28 below to the orion-ejb-jar.xml file of the EJB-module.


          <orion-ejb-jar>
              <enterprise-beans>
                  <session-deployment
                      name="myBean"
                      timeout="17"
                  />
              </enterprise-beans>
          </orion-ejb-jar>
          Listing 28: Configuring the Sessionbean's timeout period.

          Where the value of the timeout attribute is the minimum number of seconds after which the passive stateful SessionBean could be timed out. Specifying a negative value or the value "never" will keep Orion from timing out the SessionBean. The default value is 1800 seconds (30 minutes).

      4.6.3 Configuring message-driven bean cache handling

        When a message is received by a Destination where a message-driven bean is the consumer, Orion will select one of the assigned instances from the method-ready pool and invoke the onMessage method on it.


        Figure 4: UML statechart describing the simplified lifecycle of a MDB.

        The configured miniumum number of instances will be kept in the method-ready pool. Exceeding numbers of instances might be removed by Orion calling their ejbRemove() method after that the instances has been unused for a time longer than the configured timeout period, or if the total number of instances exceeds the configured maximum number of instances allowed.

        4.6.3.1 Configuring the MDB's timeout period

          By default, Orion keeps a MDB in the method-ready pool for 60 seconds, where after Orion might remove the instance by calling its ejbRemove() method. To change this behaviour, add an entry like shown in listing 29 below to the MDB's entry in the EJB-modules orion-ejb-jar.xml file:


          <orion-ejb-jar>
              <enterprise-beans>
                  <messge-driven-deployment
                      name="myBean"
                      cache-timeout="120"
                  />
              </enterprise-beans>
          </orion-ejb-jar>
          Listing 29: Configuring the message-driven bean's cache timeout period.

          Where the value of the cache-timeout attribute is the minimum number of seconds to keep the MDB in the method-ready pool. A value of "0" means that the MDB should never be kept in the method-ready pool. A value of "never" means that the MDB should never be removed from the method-ready pool. The default value is 60.

        4.6.3.2 Configuring the maximum number of cached MDB instances

          By default, Orion keeps any number of cached MDB instances in the method-ready pool. To change this behaviour, add an entry like shown in listing 30 below to the orion-ejb-jar.xml file of the EJB-module for the MDB in question:


          <orion-ejb-jar>
              <enterprise-beans>
                  <messge-driven-deployment
                      name="myBean"
                      max-instances="50"
                  />
              </enterprise-beans>
          </orion-ejb-jar>
          Listing 30: Configuring the maximum number of instances to be held in the method-ready pool.

          Where the value of the max-instances attribute is the maximum number of instances to be kept in the method-ready pool. The default value is "-1", which implies an infinite number.

        4.6.3.3 Configuring the minimum number of cached MDB instances

          By default, Orion does not instantiate any instances when the Application is started up. To change this behaviour, add an entry like shown in listing 31 below to the orion-ejb-jar.xml file of the EJB-module:


          <orion-ejb-jar>
              <enterprise-beans>
                  <messge-driven-deployment
                      name="myBean"
                      min-instances="5"
                  />
              </enterprise-beans>
          </orion-ejb-jar>
          Listing 31: Configuring the minimum number of instances to be held in the method-ready pool.

          Where the value of the min-instances attribute is the minimum number of instances to be kept in the method-ready pool. The default value is "0". Any specified number of instances will be instantiated by Orion at Application startup.

    4.7 Configuring Container Managed Persistence

      4.7.1 Configuring the DataSource to use for CMP

        By default, Orion configures the CMP EntityBean to use the default DataSource, with the default Datasource being the first configured DataSource encountered at deployment time. If a default-datasource has been defined in the Applications orion-application.xml file, this DataSource will be used by default.

        To change the DataSource to use for the CMP EntityBean, add an entry like shown in listing 32 below to the EntityBeans entry in the EJB-module's orion-ejb-jar.xml file:


        <orion-ejb-jar>
            <enterprise-beans>
                <enity-deployment
                    name="myBean"
                    data-source="jdbc/myDS"
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 32: Configuring the DataSource to use for a CMP EntityBean.

        Where the value of the data-source attribute should be the location where a OrionCMTDataSource (the ejb-location of a DataSource-entry in data-sources.xml) is bound.

      4.7.2 Configuring exclusive write access mode for CMP

        By default, Orion expects to have exclusive write (update) access to the database backend. To configure this setting, add an entry like shown in listing 33 below:


        <orion-ejb-jar>
            <enterprise-beans>
                <enity-deployment
                    name="myBean"
                    exclusive-write-access="false"
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 33: Configuring exclusive write access

        Where the value of the exclusive-write-access attribute should be set to "false" if Orion does not have exclusive write access to the database backend. The default value is "true". Setting this value to "false" will have an impact on performance, as Orion will need to query the database at the start of every transaction.

        If the entity is being replicated and needs to use transactional writes, this value should be set to "false".

      4.7.3 Configuring the table to use for CMP Entities

        By default, Orion tries to use the value of the abstract-schema-name tag of the Entity descriptor as the name of the table to use for persisting its state. This name might then be appended/prepended with a suffix and/or have its case changed in order to abide the column rules stated in schema configuration used.

        To change this behaviour, add an entry like the one given in listing 34 below to the orion-ejb-jar.xml of the EJB-module:


        <orion-ejb-jar>
            <enterprise-beans>
                <enity-deployment
                    name="myBean"
                    table="myBean"
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 34: Specifying the name of the database table to use for CMP.

        Where the value of the table attribute is the name of the table to use for persisting the state of the Entity with CMP.

      4.7.4 Configuring the isolation level for an Entity's database actions

        By default, Orion uses the default isolation-level of the underlying DataSource used. The isolation-levels are used to decide how concurrent changes to the DataSource should be handled, and when the changes can be read.


        <orion-ejb-jar>
            <enterprise-beans>
                <enity-deployment
                    name="myBean"
                    isolation="committed"
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 35: Configuring the isolation-level for an Entity's database actions

        Where the value of the isolation attribute is either "serializable", "uncommitted", "committed" or "repeatable_read", with the default value being the default isolation-level of the DataSource used. Notice that the configured value must be supported by the DataSource in use. A short description of each isolation-level is given below.

          uncommitted - indicates that dirty reads, non-repeatable reads and phantom reads can occur. This level allows a row changed by one transaction to be read by another transaction before any changes in that row have been committed (a "dirty read"). If any of the changes are rolled back, the second transaction will have retrieved an invalid row.

          commited - indicates that dirty reads are prevented; non-repeatable reads and phantom reads can occur. This level only prohibits a transaction from reading a row with uncommitted changes in it.

          repeatable_read - indicates that dirty reads and non-repeatable reads are prevented; phantom reads can occur. This level prohibits a transaction from reading a row with uncommitted changes in it, and it also prohibits the situation where one transaction reads a row, a second transaction alters the row, and the first transaction rereads the row, getting different values the second time (a "non-repeatable read").

          serializable - indicates that dirty reads, non-repeatable reads and phantom reads are prevented. This level includes the prohibitions in repeatable_read and further prohibits the situation where one transaction reads all rows that satisfy a WHERE condition, a second transaction inserts a row that satisfies that WHERE condition, and the first transaction rereads for the same condition, retrieving the additional "phantom" row in the second read.

      4.7.5 Configuring Container Managed finder methods

        To override EJB-QL entries or if using EJB 1.1, it is possible to define the SQL query part following the WHERE keyword in the statement.

        Method arguments can be referenced to by specifying $[number], where [number] is the method's argument number (1 for first argument, 2 for second and so on).

        CMP fields can be referenced to by specifying $[name], where [name] is the name of a CMP field.

        To specify the WHERE part of the finders SQL, add an entry like shown in listing 36 below to the orion-ejb-jar.xml entry of the CMP Entity:


        <orion-ejb-jar>
            <enterprise-beans>
                <enity-deployment
                    name="myBean"
                    <finder-method
                        sql-query="$1 = $myCMPField AND $myOtherCMPField > 5"
                    />
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 36: Specifying the WHERE clause of a finders SQL

        Where the value of the sql-query attribute of the finder-method tag contains the WHERE clause of the finders SQL.

    4.8 Configuring clustering

      4.8.1 Configuring SessionBean cluster replication

        Add the attribute replication with a value of "cluster" to cluster-enable the SessionBean (the default value is "none" which means that the SessionBean is not clustered).


        <orion-ejb-jar>
            <enterprise-beans>
                <session-deployment
                    name="myBean"
                    replication="cluster"/>
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 37: Configuring the SessionBean to replicate its state over a cluster.

        For more information about clustering, please see the EJB State replication article.

      4.8.2 Configuring EntityBean cluster replication

        Add the attribute clustering-schema with a value of "asynchronous-cache" to cluster-enable the Entity bean (the default value is "default" which means that the Entity is not clustered)


        <orion-ejb-jar>
            <enterprise-beans>
                <enity-deployment
                    name="myBean"
                    clustering-schema="asynchronous-cache"
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 38: Configuring the EntityBean to replicate its state over a cluster.

        For more information about clustering, please see the EJB State replication article.

    4.9 Configuring transactional behaviour

      4.9.1 Configuring the maximum number of transaction retries

        By default, a transaction that fails due to system-level failures will be retried 3 times for SessionBeans and not at all for EntityBeans.

        To change this behaviour, add an entry like shown in listing 39 and 40 to the EJB-module's orion-ejb-jar-xml file.


        <orion-ejb-jar>
            <enterprise-beans>
                <session-deployment
                    name="myBean"
                    max-tx-retries="22"
                />
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 39: Configuring the number of times to retry a failed transaction.


        <orion-ejb-jar>
            <enterprise-beans>
                <entity-deployment
                    name="myBean"
                    max-tx-retries="17"
                />
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 40: Configuring the number of times to retry a failed transaction.

        Where the value of the max-tx-retries attribute is the number of times to retry a transaction that failed due to system-level errors.

      4.9.2 Configuring call timeout

        By default, Orion lets a EJB wait forever for a called busy EJB to get available. To change this behaviour and make the calling EJB throw a RemoteException after waiting a certain period of time, add an entry like shown in listing 41 or 42 below to the orion-ejb-jar.xml file of the EJB-module for the calling EJB:


        <orion-ejb-jar>
            <enterprise-beans>
                <session-deployment
                    name="myBean"
                    call-timeout="30"
                />
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 41: Configuring the SessionBean call timeout period


        <orion-ejb-jar>
            <enterprise-beans>
                <entity-deployment
                    name="myBean"
                    call-timeout="30"
                />
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 42: Configuring the EntityBean call timeout period

        In the example above, the EJB with the name myBean (the value of the name attribute should match the name of the EJB in the EJB-module's ejb-jar.xml file) has been configured to wait 30 miliseconds (the value should be expressed as a number of milis) when calling methods on a busy EJB. If the called EJB is still busy after the specified time-period, the situation will be handled as a deadlock and a RemoteException will be thrown. The default value of the call-timeout attribute is "0" which is interpreted as "forever".

    4.10 Configuring security

      4.10.1 Mapping security roles to Users/Groups

        The Orion default behaviour to handle mapping of Roles defined in an ejb-jar.xml file of an EJB-module to Groups is to assume that the Role should be mapped to a Group with the same name as the Role .

        To change how roles are mapped to Users/Groups, use the security-role-mapping tag in the orion-ejb-jar.xml file of the EJB-module, as described in this article.


        <orion-ejb-jar>
            <assembly-descriptor>
                <security-role-mapping name="shopkeeper">
                    <group name="administrators">
                </security-role-mapping>
            </assembly-descriptor>
        </orion-ejb-jar>
        Listing 43: A Role mapping entry in orion-ejb-jar.xml. The entry maps the Role "shopkeepers" to the Group "administrators".

        If the EJB-module is part of a J2EE Application it is enough to specify the role-mappings in the orion-application.xml file as described in the Application deployment article. Any mapping defined in the deployment descriptor of the J2EE Application would be inherited by its EJB-modules. The EJB-module would still be able to override any such mappings.

      4.10.2 Mapping default security roles to Users/Groups

        By default, Orion lets any User access methods without any specified method-permission by adding an entry like in listing 38 below to the orion-ejb-jar.xml file of the EJB-module:


        <orion-ejb-jar>
            <assembly-descriptor>
                <default-method-access>
                    <security-role-mapping name="&lt;default-ejb-caller-role&gt;" impliesAll="true">
                </default-method-access>
            </assembly-descriptor>
        </orion-ejb-jar>
        Listing 44: The default security role for methods without any specified method-permissions.

        Where the <default-ejb-caller-role> is an Orion specific role defining access to EJB methods wihtout any specified method-persmissions.

        To change how roles are mapped to Users/Groups, use the security-role-mapping tag in the orion-ejb-jar.xml file of the EJB-module, as described in this article.

    4.11 Configuring Factories and Destinations for Message-driven beans

      4.11.1 Configuring the JNDI location of the Connection factory to use

        By default, Orion will use the Connection factory of the right type (Topic/Queue) defined first in the JMS configuration file as the default Connection Factory for any MDB. To change this behaviour, add an entry like shown in listing 45 to the orion-ejb-jar.xml file of the EJB-module:


        <orion-ejb-jar>
            <enterprise-beans>
                <message-driven-deployment
                    name="myBean">
                    factory-location="jms/QueueConnectionFactory"
                </message-driven-deployment>
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 45: Configuring the Connection factory to use for a message-driven bean.

        Where the value of the factory-location attribute is the JNDI location of a connection Factory of the type (Topic or Queue) the MDB requires, usually configured in the JMS configuration file.

      4.11.2 Configuring the JNDI location of the Destination to use

        By default, Orion will use the Destination of the right type (Topic/Queue) defined first in the JMS configuration file as the default Destination for any MDB. To change this behaviour, add an entry like shown in listing 46 to the orion-ejb-jar.xml file of the EJB-module:


        <orion-ejb-jar>
            <enterprise-beans>
                <message-driven-deployment
                    name="myBean">
                    destination-location="jms/demoQueue"
                </message-driven-deployment>
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 46: Configuring the Destination to use for a message-driven bean.

        Where the value of the destination-location attribute is the JNDI location of a Destination of the type (Topic or Queue) the MDB requires, usually configured in the JMS configuration file.

      4.11.3 Configuring the client-id for a durable subscriber

        By default, Orion will use a concatenation of the deployment name of the application and the ejb-name as the unique identifier for a message-driven bean intended as a durable subsriber Topic. To specify a client-id , add an entry like shown in listing 47 below to the orion-ejb-jar.xml file of the EJB-module:


        <orion-ejb-jar>
            <enterprise-beans>
                <message-driven-deployment
                    name="myBean">
                    client-id="clientID"
                </message-driven-deployment>
            </enterprise-beans>
        </orion-ejb-jar>
        Listing 47: Configuring the client-id to use for a message-driven bean intended as a durable subscriber Topic.

        Where the value of the client-id attribute is the unique identifier for this durable subsriber Topic.

Copyright © 2005 IronFlare AB