Beans and the Blueprint Container

In the Blueprint programming model, you declare beans by using the bean element. You specify argument elements to provide the arguments that are used for object construction, and you specify property elements to provide the injected properties.

You can specify the value of argument and property elements by using a value or ref attribute, or you can use an inline declaration in an element. The ref attribute specifies the ID of a top-level manager, and is used to obtain an object from the referenced manager as the argument or property value. The inline value can be any XML value that is described in Object values and the Blueprint Container.

The following bean.xml example code defines a single bean called accountOne that is implemented by the org.apache.aries.simple.Account plain old Java™ object (POJO).

<?xml version="1.0" encoding="UTF-8"?> 
<blueprint xmlns="https://www.osgi.org/xmlns/blueprint/v1.0.0">    
   <bean id="accountOne" class="org.apache.aries.simple.Account" /> 
</blueprint>

Bean Construction

To construct an object, first the Blueprint Container finds the correct constructor or factory method with a compatible set of parameters that match the arguments that are specified in the XML. By default, the Blueprint Container uses the number and order of the argument elements in XML to find the correct constructor or method. If the argument elements in their current order do not map to the parameters, the Blueprint Container reorders the argument elements and attempts to find the best-fitting arrangement.

You can specify additional attributes, such as index or type, on the argument element so that it is easier for the Blueprint Container to find the correct constructor, method, or parameter arrangement. For example, the type attribute specifies a class name used to match the argument element to a parameter by the exact type.

You can construct a bean in either of the following ways:

• Use a class constructor.
• Use a static factory method .
• Use an instance factory method.

The following partial Java class and Blueprint XML example code shows how to construct a bean by using a class constructor. The class attribute specifies the name of the Java class to instantiate. The Blueprint Container creates the Account object by passing the value 1 as the argument to the constructor.

public class Account {
   public Account(long number) {
      ...
   }
   ...
}

<bean id="accountOne" class="org.apache.aries.simple.Account">        
   <argument value="1"/>    
</bean> 

The following partial Java class and Blueprint XML example code shows how to construct a bean by using a static factory method. The class attribute specifies the name of the class that contains a static factory method. The factory-method attribute specifies the name of the static factory method. The Blueprint Container calls the createAccount() static method on the StaticAccountFactory class and passes the value 2 as the argument to create the Account object.

public class StaticAccountFactory {
   public static Account createAccount(long number) {
      return new Account(number);
   }
} 

<bean id="accountTwo" class="org.apache.aries.simple.StaticAccountFactory"
   factory-method="createAccount">
   <argument value="2"/>
</bean> 

The following partial Java class and Blueprint XML example code shows how to construct a bean by using an instance factory method. You use two managers; one manager is a factory, and the other uses the factory to create an object. The factory-ref attribute specifies the ID of a top-level bean or a reference manager that acts like a factory. The provided factory object must have a factory method, as specified by the factory-method attribute.

The accountFactory bean is the factory. The Blueprint Container first creates the AccountFactory instance with its own arguments and properties. In this example, a single argument, the factory name, is specified. The Blueprint Container then calls the createAccount() method on the AccountFactory instance and passes the value 3 as the argument to create the Account object.

public class AccountFactory {
   public AccountFactory(String factoryName) {
      ...
   }
   public Account createAccount(long number) {
      return new Account(number);
   }
}

<bean id="accountFactory" class="org.apache.aries.simple.AccountFactory">
   <argument value="account factory"/>      
</bean>

<bean id="accountThree"
      factory-ref="accountFactory" 
      factory-method="createAccount">   
   <argument value="3"/>
</bean>

Bean properties

You can use the property element to inject property values into beans. Properties are injected immediately after the bean is constructed. The following partial Java class and Blueprint XML example code creates the Account bean, then sets the description property by using the Java Beans naming convention.

public class Account {      
   public Account(long number) {
      ...
   }
   public void setDescription(String desc) {
      ...
   }
}

<bean id="accountOne" class="org.apache.aries.simple.Account">
   <argument value="1"/>
   <property name="description" value="#1 account"/>
</bean>

You can use property injection to wire beans together. In the following Blueprint XML example code, the accountOne bean is injected with a Currency bean.

public class Account {      
   public Account() {
      ...
   }
   public void setCurrency(Currency c) {
      ...
   }
}

public class Currency {      
   public Currency() {
      ...
   }
}

<bean id="accountOne" class="org.apache.aries.simple.Account">
   <property name="currency" ref="currency" />
</bean>

<bean id="currency" class="org.apache.aries.simple.Currency" />

Configuring bean security

Optionally, you can configure bean security so that the methods of the bean can be accessed only by users that are in a specified role.

You configure security by specifying an <access-constraint> element. The <access-constraint> element has a role attribute that defines the name of the role.

To define access controls for a particular role, use the Security role to user or group mapping panel in the WebSphere® Application Server administrative console.

In the following example, the methods of the secureBean1 bean are accessible only by users in the role called "ROLE1":

<bean
  id="secureBean1"
  class="com.ibm.ws.eba.wab.componenttest.blueprint.secure.BlueprintSecureServiceImpl">
  <access-constraint role="ROLE1" />
</bean>

For the bean security configuration to be effective, application security must be enabled in WebSphere Application Server.

If you do not specify an <access-constraint> element, the bean is not secured; this means that all the methods of the bean can be accessed by any user.