Bean Provider Responsibilities

Application Assembler Responsibilities

The bean provider is responsible for most of the deployment descriptor contents, but there's still work to be done by the other roles as well. An application assembler builds applications from EJBs. The application assembler starts with the deployment information provided by one or more bean providers and adds to it or modifies it to compose an application. Most of the additions take place in the assembly-descriptor part of the deployment file.

The assembly-descriptor Element

The assembly-descriptor element is technically optional, but you would have trouble building a non-trivial application without using the declarative security and transactional mechanisms it controls. This element can contain any number of security-role , method-permission , container-transaction entries, and a single exclude-list entry provided by either the application assembler or the deployer.

security-role

The bean provider can define security role names and reference them in bean code, but the roles defined by the application assembler are the ones the deployer maps directly to the security mechanisms found in the target operational environment. The application assembler defines logical security roles using security-role entries, which consist of an optional description and a role- name . These roles define the logical groupings of users that can be referenced to restrict access to an EJB's methods . They're not the same as the actual users and user groups defined in the target environment ”they're just the logical roles the deployer will eventually map to that environment.

The application assembler also completes any security-role-ref entries defined by the bean provider by adding a role-link element to each one. This entry defines the security- role to which a security-role-ref corresponds. You can use the same name for both roles if you want. The following example shows a completed security-role-ref and its corresponding security-role :

 <ejb-jar>    <enterprise-beans>      ...      <entity>        <ejb-name>EnglishAuction</ejb-name>        ...        <security-role-ref>          <description>The auction restricts some operations to valid bidders          </description>          <role-name>bidder</role-name>          <role-link>registered-bidder</role-link>        </security-role-ref>        ...      </entity>      ...    </enterprise-beans>    <assembly-descriptor>      <security-role>        <description>A role to represent users who have registered with the          system as authorized auction participants        </description>        <role-name>registered-bidder</role-name>      </security-role>    </assembly-descriptor>    ...  </ejb-jar> 

Also related to security roles, the application assembler can define security-identity elements within the entity , message-driven , and session elements that determine whether a caller's security identity is used to execute an EJB's methods or if a specified role is used. A security-identity element contains an optional description and either an empty use- caller-identity tag or a run-as element. The use-caller-identity choice is valid only for entity and session beans, but a run-as can be assigned to a message-driven bean as well. This element can contain a description along with a role-name to associate with all calls to a bean's methods. As an example, the following deployment would associate the registered- bidder role with all calls made by the AuctionHouse session bean:

 <ejb-jar>    <enterprise-beans>      ...      <session>        <ejb-name>AuctionHouse</ejb-name>        ...        <security-identity>          <run-as>            <description>This role needs to be associated with valid bidders            </description>            <role-name>registered-bidder</role-name>          </run-as>        </security-identity>        ...        </session>      ...    </enterprise-beans>    ...  </ejb-jar> 

Assigning a run-as identity to a bean affects the method permissions associated with it but not any calls to isCallerInRole made within the bean's code. The isCallerInRole method always performs its checks against the caller's actual security identity and not any assigned run-as identity.

Caution

Specifying to use a run-as identity is far less common than using the caller's actual security identity when calling other EJBs. Obviously, you must be careful to not open up functionality to users that should be restricted from it.

method-permission

The security roles defined by the application assembler can apply to a bean provider's use of security-role-ref entries, but they're used more in declaratively restricting access to entity and session bean methods. Home and component interface methods can be restricted through method-permission entries that associate one or more security roles with one or more bean methods. The roles are identified with role-name entries that must match a role- name specified for one of the security-role entries. One or more method elements then follow that identify methods that can only be accessed by callers associated with one of the specified roles. For example, the following permission entry would restrict bid submissions to registered bidders and their agents :

 <method-permission>    <role-name>registered-bidder</role-name>    <role-name>authorized-agent</role-name>    <method>      <ejb-name>AuctionHouse</ejb-name>      <method-name>submitBid</method-name>    </method>  </method-permission> 

The application assembler also can indicate that some methods should not be checked for security before the container invokes the method. The assembler can configure this behavior by using the unchecked element instead of a role-name . The following snippet shows how this might be done:

 <method-permission>    <unchecked/>    <method>      <ejb-name>AuctionHouse</ejb-name>      <method-name>submitBid</method-name>    </method>  </method-permission> 

See "Using Container-Managed Transactions," p. 344 for examples of the other forms of the method element.

If you don't assign any method permissions to a particular bean's methods, this is interpreted as meaning that any role should be allowed to access any of the bean's methods. If you assign role restrictions to some but not all of a bean's methods, it's assumed that any methods without a role assignment shouldn't be accessible at all.

container-transaction

The container-transaction entries are where the application assembler defines the transactional behavior for beans that use container-managed transaction demarcation. The application assembler can't affect the transactional nature of an EJB that uses bean-managed demarcation . Each container-transaction entry has an optional description , one or more method entries, and a trans-attribute . The methods that a particular transaction attribute applies to are specified in the same way methods are identified within the method- permission element. The trans-attribute must be specified as NotSupported , Supports , Required , RequiresNew , Mandatory , or Never .

For a particular EJB, the application assembler must either specify the transaction attribute for every method that requires one or for none of them so that the deployer can do it. Table 15.3 summarizes the methods that require a transaction attribute when container-managed transaction demarcation is used.

Table 15.3. Transaction Attribute Requirements

EJB Type	Methods Requiring a Transaction Attribute
Entity	The methods declared in the component interface and its superinterfaces excluding getEJBHome , getEJBLocalHome , getHandle , getPrimaryKey , and isIdentical . The methods declared in the home interface and its superinterfaces excluding those declared by getEJBMetaData and getHomeHandle .
Session	The methods declared in the component interface and its superinterfaces excluding those declared by EJBObject and EJBLocalObject .
Message-Driven	The onMessage method.

The following example illustrates how to declare the Required attribute for all methods of a particular entity bean:

 <container-transaction>    <method>      <ejb-name>EnglishAuction</ejb-name>      <method-name>*</method-name>    </method>    <trans-attribute>Required</trans-attribute>  </container-transaction> 

If you needed a particular method in the EnglishAuction bean to have a transaction attribute other than Required , you could do something like this:

 <container-transaction>    <method>      <ejb-name>EnglishAuction</ejb-name>      <method-name>*</method-name>    </method>    <trans-attribute>Required</trans-attribute>  </container-transaction>  <container-transaction>    <method>      <ejb-name>EnglishAuction</ejb-name>      <method-name>getTimeLeft</method-name>    </method>    <trans-attribute>Supports</trans-attribute>  </container-transaction> 

Refer to Chapter 12, "Transactions," for a description of each of the allowed transaction attributes.

For more information on declarative transaction management, see "Using Container-Managed Transactions," p. 344 .

exclude-list

The application assembler can add the exclude-list entry so that a set of methods should not be called. The deployer should configure the enterprise bean's security such that no access is permitted to any method in the exclude-list . The entry has an optional description and one or more method entries. The following example illustrates how to declare methods that should be excluded:

 <exclude-list>    <description>A method that should not be available to clients</description>    <method>      <ejb-name>EnglishAuction</ejb-name>      <method-name>someUnavailableMethodName</method-name>    </method>  </exclude-list> 

Modifying enterprise-beans Entries

Besides supplying the assembly-descriptor portion of the deployment descriptor, the application assembler can also modify some of the entries found in the enterprise-beans section and add entries that were not specified by the bean provider. You saw an example of this already with the role-link element of a security-role-ref . This is an example of information never supplied by the bean provider. In other cases, the application assembler may supply or modify env-entry-value entries to define values for environment properties or description entries to better define how an element is being used or provide more instructions to the deployer. It's also possible for naming conflicts to arise if multiple ejb-jar files are merged. Here, an application assembler might have to change an entry such as an ejb-relation-name to resolve a conflict.

env-entry-value

The application assembler may change the value of an environment entry specified by the bean provider or add a value where one hasn't been given. The value specified for an env-entry-value is interpreted as a String that must be acceptable to the one-argument constructor of the class assigned to the entry. For example, you could specify True for a java.lang.Boolean entry or 12.3 for a java.lang.Double . You must supply a single character value for a java.lang.Character entry.

ejb-link

The application assembler can add the ejb-link entry to any ejb-ref or ejb-local-ref element declared by the bean provider to complete it. An ejb-link associates a bean provider reference with a target EJB using the ejb-name of the referenced bean to identify it. The application assembler can provide just the ejb-name or, to prevent any possible name conflicts, specify the pathname of the ejb-jar that contains the bean followed by a # and the ejb-name . The pathname must be given relative to the current ejb-jar file . The following examples provides an example of using the ejb-link entry in an ejb-local-ref element:

 <ejb-local-ref>    <description>This EJB reference is used to locate an auction's item    </description>    <ejb-ref-name>ejb/Item</ejb-ref-name>    <ejb-ref-type>Entity</ejb-ref-type>    <local-home>com.que.ejb20.item.model.ItemHome</local-home>    <local>com.que.ejb20.item.model.Item</local>    <ejb-link>Item</ejb-link>  </ejb-local-ref>