Creating blueprint XML files

The blueprint configuration file contains the component assembly and configuration information for a bundle. The file describes how components are registered in the OSGi service registry or how they look up services from the OSGi service registry. This information is used at run time to instantiate and configure the required components when the bundle is started.

Procedure

  1. Right-click your bundle project and select New > Blueprint File. The New Blueprint File wizard opens.
  2. In the File name field, type the name of your blueprint configuration file and then click Next.
  3. In the Add or Remove Additional Blueprint Namespaces page of the wizard, select the namespaces that you want to add to your blueprint file.
    You can add namespaces for blueprint extensions, JPA, Resource reference, and Transactions.
    Learn more about blueprint namespaces:
    Table 1. Description of blueprint namespaces
    Schema URL Description
    Blueprint extension http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0

    IBM® Blueprint extensions

    Extensions to the OSGi Blueprint programming model, such as field injection.
    Blueprint security http://www.ibm.com/appserver/schemas/blueprint/security/v1.0.0

    IBM Blueprint security

    Configure bean security so that the methods of the bean can be accessed only by users that are assigned a specified role.

    More information: Blueprint security and OSGi applications
    JPA http://aries.apache.org/xmlns/jpa/v1.0.0

    JPA Blueprint support

    Provides Java™ Persistence API (JPA) integration into Blueprint. Persistence units and persistence contexts can be injected into Blueprint managed beans.
    Resource reference http://www.ibm.com/appserver/schemas/8.0/blueprint/resourcereference

    Blueprint resource reference support

    Provides for objects that are declared in WebSphere® Application Server JNDI, such as data sources and connection factories to be injected into Blueprint managed beans.
    Transactions http://aries.apache.org/xmlns/transactions/v1.0.0

    Blueprint transaction support

    Allows the developer to declare transaction requirements for Blueprint managed beans.
    Note: If you want to add other namespaces not in this list, switch to the Source view and type in the namespace.
  4. Click Finish. The blueprint configuration file opens in the editor.
  5. Click Add to add the component assembly and configuration information to your blueprint configuration file.
    Bean
    The bean element defines the blueprint component that is instantiated. Click OK to add arguments and properties to the bean.
    Learn more about Bean attributes:
    ID
    The id attribute identifies the component. It is mandatory if the component is referenced from elsewhere in the blueprint, for example if it is referenced from a service definition.
    Class
    The class attribute specifies which implementation class of the component is instantiated.
    Activation
    This optional attribute defines the activation mode for the manager. Two activation modes are supported:
    eager
    The manager is activated during Blueprint Container initialization.
    lazy
    The manager is activated on demand.
    By default activation is set to eager.
    Scope
    Depending on the scope setting, a bean manager can create single or multiple object instances. The Blueprint Container specification defines two main scopes:
    singleton
    The bean manager creates a single instance of the bean and returns that instance every time the manager is asked to provide an object.
    prototype
    The bean manager creates a new instance of the bean every time the manager is asked to provide an object.
    By default, the singleton scope is assumed for top-level bean managers. The scope attribute cannot be set on an inlined bean manager, so the inlined managers are always considered to have prototype scope.
    Depends On
    Specifies a list of manager IDs. The listed managers are activated first before the manager is activated. A manager can have explicit and implicit dependencies. The dependsOn attribute defines the explicit dependencies. The implicit dependencies are defined by the references to other managers within a manager definition.
    Factory reference
    Specifies the ID of a bean or reference manager that acts as a factory. The specified object must have a factory method as specified by the factory method attribute.
    Destroy method
    Specifies a method to be called when the Blueprint Container is destroying the object instance.
    Factory method
    Specifies the name of the static factory method.
    Initialization method
    The initialization method is called when the component is created. If you do not want to invoke a method during bundle initialization, remove this attribute.
    Reference
    The reference element specifies services that are found in the service registry. Click OK to add items to the reference.
    Learn more about Reference attributes:
    ID
    The id attribute identifies the component. It is mandatory if the component is referenced from elsewhere in the blueprint, for example if it is referenced from a service definition.
    Interface
    The interface attribute refers to the interface that the component class implements.
    Activation
    This optional attribute defines the activation mode for the manager. Two activation modes are supported:
    eager
    The manager is activated during Blueprint Container initialization.
    lazy
    The manager is activated on demand.
    By default activation is set to eager.
    Availability
    Controls requirements by the service reference manager that at least one service, which matches selection criteria, exists before the blueprint container initialization continues. The availability attribute has two values:
    optional
    Services matching the criteria do not have to exist.
    mandatory
    At least one service that matches the criteria must exist.
    By default availability is set to mandatory.
    Filter
    Specifies the filter expression for service selection.
    Timeout
    Specifies the amount of time, in milliseconds, a proxy waits for a backing service to become available.
    Component name
    Specifies the component searched by the filter.
    Depends On
    Specifies a list of manager IDs. The listed managers are activated first before the manager is activated. A manager can have explicit and implicit dependencies. The dependsOn attribute defines the explicit dependencies. The implicit dependencies are defined by the references to other managers within a manager definition.
    Reference List
    The reference-list element enables the reference element to find multiple matching services. Click OK to add items to the reference list.
    Learn more about Reference list attributes:
    ID
    The id attribute identifies the component. It is mandatory if the component is referenced from elsewhere in the blueprint, for example if it is referenced from a service definition.
    Interface
    The interface attribute refers to the interface that the component class implements.
    Activation
    This optional attribute defines the activation mode for the manager. Two activation modes are supported:
    eager
    The manager is activated during Blueprint Container initialization.
    lazy
    The manager is activated on demand.
    By default activation is set to eager.
    Availability
    Controls requirements by the service reference manager that at least one service, which matches selection criteria, exists before the blueprint container initialization continues. The availability attribute has two values:
    optional
    Services matching the criteria do not have to exist.
    mandatory
    At least one service that matches the criteria must exist.
    By default availability is set to mandatory.
    Filter
    Specifies the filter expression for service selection.
    Member type
    Specifies the type of members provided by the reference list manager. The member type attribute supports:
    service-object
    Injects a list of service proxy objects.
    service-reference
    Injects a list of service reference objects.
    By default member type is set to service-object.
    Component name
    Specifies the component searched by the filter.
    Depends On
    Specifies a list of manager IDs. The listed managers are activated first before the manager is activated. A manager can have explicit and implicit dependencies. The dependsOn attribute defines the explicit dependencies. The implicit dependencies are defined by the references to other managers within a manager definition.
    Service
    The service element defines the export of a component to the OSGi service registry. Click OK to add items to the service.
    Learn more about Service attributes:
    ID
    The id attribute identifies the component. It is mandatory if the component is referenced from elsewhere in the blueprint, for example if it is referenced from a service definition.
    Interface
    The interface attribute refers to the interface that the component class implements.
    Activation
    This optional attribute defines the activation mode for the manager. Two activation modes are supported:
    eager
    The manager is activated during Blueprint Container initialization.
    lazy
    The manager is activated on demand.
    By default activation is set to eager.
    Auto-Export
    The auto-export setting is specified by the auto-export attribute and supports the following four options:
    disabled
    The default value if the auto-export attribute is not specified. The list of interfaces must be specified by using the interface attribute or interfaces subelements.
    interfaces
    Register the service by using all public interfaces implemented by the service class and any of its super classes.
    class-hierarchy
    Register the service by using the service class and any of its public super classes.
    all-classes
    Combines interfaces and class-hierarchy options.
    Ranking
    You can use the ranking attribute to expose the service with a specific ranking.
    Reference
    The ref attribute refers to the component id of the exported component. This id is defined in the component element.
    Depends On
    Specifies a list of manager IDs. The listed managers are activated first before the manager is activated. A manager can have explicit and implicit dependencies. The dependsOn attribute defines the explicit dependencies. The implicit dependencies are defined by the references to other managers within a manager definition.
    Type Converters
    The type-converters element converts values between data types. Click OK to add items to the type converter.

    For more information about the blueprint configuration file, see the Help topics OSGi Blueprint XML files and OSGi Blueprint Container Specification.

  6. Click Open WebSphere Blueprint Bindings Descriptor to create an OSGi blueprint configuration file that contains the resource references to authentication alias binding for a bundle.

    If an OSGi application contains an OSGi blueprint binding configuration file when it is deployed as an asset, the binding configuration file provides the default authentication alias values that are used when binding the resource references.

    For more information about the blueprint binding file, see Creating blueprint binding XML files.

  7. Click Add and remove additional blueprint namespaces to add namespaces to the blueprint XML file.
    1. In the Blueprint Namespaces dialog, select the namespaces that you want to add to the blueprint file.
    2. Click Finish.

    These elements are enabled based on the blueprint namespaces that you add to the blueprint XML file.

    Context
    The bpjpa:context element extends the Apache Aries blueprint specification for JPA beans used within blueprint transactions. This element is added when you add the JPA namespace. Click Add to add attributes to the element.
    Properties placeholder
    The bpext:property-placeholder element adds extensions to the Apache Aries blueprint specification. This element is added when you add the Blueprint extension namespace. Click Add to add attributes to the element.
    Resource reference
    The bpresref:resource-reference element injects resource references, for example data sources, into beans or services. This element is added when you add the Resource reference namespace. Click Add to add attributes to the element.
    Transaction
    The tx:transaction element extends the Apache Aries blueprint specification by adding transaction properties to the blueprint file. This element is added when you add the Transaction namespace. Click Add to add attributes to the element.
  8. Save the file.

    For more information about OSGi blueprint XML files, see the following subtopics: