Blueprint Advanced Features

– Lin Sun– Apache Aries and

Geronimo committer and PMC member

– OSGi Enterprise Expert Group (EEG) member

– Software Engineer at IBM

http://arrowheadaddict.com/files/2009/01/blueprint.jpg

Agenda

– Aries Blueprint Container Overview– Configuration– Beans, Services, Service References– Bean Interceptors– Declarative Transaction– JPA Blueprint Integration– Message Driven Service– Annotation– AriesTrader Application Demo– Conclusion

Aries Blueprint Container– Clean implementation based on Blueprint

Specification in OSGi Compendium R4.2• Dependency Injection framework for

OSGi• Designed to work with plain old Java

objects (POJOs)• Handle the OSGi dynamics

– Integrated in Geronimo, Felix Karaf, etc.

Aries Blueprint Container (cont.)

– Extender Pattern

– Blueprint XML Definition files and Metadata

Configuration

– Blueprint xml uses blueprint namspace

blueprint ::= <type-converters> manager* manager ::= <bean> | <service> | service reference

service-reference ::= <reference> | <reference-list> type-converters ::= <bean> | <ref>

Service & inline bean

FooImpl foo = new FooImpl();

foo.setA(5);

Hashtable props = new Hashtable();

props.put(“key”, “value”);

bundleContext.registerService(org.apache.aries.blueprint.sample.Foo.class.getName(), foo, props);

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

<service interface=" class="org.apache.aries.blueprint.sample.Foo"> <service-properties> <entry key="key" value="value" /> </service-properties>

<bean id="foo" class="org.apache.aries.blueprint.sample.FooImpl">

<property name="a" value="5" />

</bean>

</service>

</blueprint>

Blueprint top elementBlueprint top element Blueprint namespace uriBlueprint namespace uri

Service manager definitionService manager definition

Bean Constructor example

Account accountOne = new Account(1);

Bean Constructor example 2

Account accountTwo = StaticAccountFactory.createAccont(2);

Bean Property example

Account accountOne = new Account(1);

accountOne.setDescription(“#1 account”);

Bean Wiring example

Account accountOne = new Account();

Currency currency = new Currency();

accountOne.setCurrency(currency);

Service example

AccountImpl account = new AccountImpl();

bundleContext.registerService(Account.class.getName(), account, new Hashtable());

Reference sample

AccountClient accountClient = new AccountClient();

ServiceReference sr = bundleContext.getServiceReference(“org.apache.aries.simple.Account”);

Account account = (Account)bundleContext.getService(sr);

accountClient.setAccount(account);

– Object injected for reference is a proxy to the service registered in the service registry

– A proxy enables the injected object to remain the same while the backing service can come and go.

Reference-list sample

– Reference-list provides a List object that contains the service proxy objects or ServiceReference objects

– Provided List object is dynamic, as it can grow and shrink as matching services change

Advanced Blueprint Features

– Config Admin– Blueprint custom namespace handler

– Bean Interceptor– Declarative Transaction– JPA Blueprint Integration– Message Driven Service– Annotation

Bean Interceptor– Why do we need interceptors?

• Declarative Transaction• Security, logging, etc

– Features of bean interceptor• Interceptor invocation prior to a bean method call(pre-call).

• Interceptor invocation following a successful bean method call (post-call)

• Interceptor invocation following an exception result to a method call.

• Interceptor ordering when 1+ interceptors are registered for the bean method.

– Working on standardization in OSGi EEG. RFP has been approved.

Declarative Transaction– Features of declarative transaction

• Provides container managed transaction for blueprint beans

• Supports 6 transaction attributes (Required, Mandatory, RequiresNew, Supports, NotSupported, and Never)

• Manage transaction boundaries in the same manner as defined for the EJB 3.0 container

• Supports bean level or bundle wide. Bean level comes with higher priority.

• Detects configuration error at deployment time

– Working on standardization in OSGi EEG. RFP has been approved.

Simple beanpublic class TestBeanImpl { … public void insertRow(String name, int value) throws SQLException { // get the user transaction service UserTransaction ut = getUserTransactionService(); // begin the user transaction ut.begin(); try { // start the operation to insert name, value into the db ... } finally { // commit the user transaction ut.commit(); } } }

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"> <bean id="TestBeanImpl" class="org.apache.aries.simple.TestBeanImpl" /> </blueprint>

Blueprint definition XML for the bean

Transaction management & application logic

Simple bean with declarative transaction

public class TestBeanImpl { … public void insertRow(String name, int value) throws SQLException { // start the operation to insert name, value into the db ... } }

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0"> <bean id="TestBeanImpl" class="org.apache.aries.simple.TestBeanImpl"> <tx:transaction method="insertRow" value="required"/> </bean> </blueprint>

Blueprint definition XML including bean level declarative

transaction for the bean

Focus on application logic

Implementation of declarative transaction– Leverages blueprint bean interceptor

• Manage the transaction boundary before the method is invoked

• Manage the transaction boundary after the method is invoked

– Leverages blueprint custom namespace handler• Transaction namespace is proposed to describe blueprint declarative transaction in blueprint definition XML.

• Blueprint extender sets the bundle’s dependency on the life cycle of the transaction namespace handler.

• Blueprint custom namespace handler is to be standardized by OSGi EEG.

– Leverage Transaction Specification in OSGi Enterprise R4.2

Priorities of transaction declaration

– Priority ordering (from high to low)• Bean level transaction element with method attribute

• Bean level transaction element when method is not specified

• Top level transaction element with both bean attribute and method attribute

• Top level transaction element with only the bean attribute

• Top level transaction element with only the method attribute

• Top level transaction element without bean or method attribute specified

– If the transaction namespace handler is not able to determine the transaction for the bean, the creation of the blueprint container will fail with blueprint FAILURE event emitted.

Declarative Transaction Examples

– For the bean requiresNew, all methods have REQUIRESNEW behavior.

– For the bean noTx, all methods have NEVER behavior. – For the bean someTx, methods starting with "get" are MANDATORY,

and all other methods are REQUIRED. – For the bean anotherBean, all methods that start with "get" are

SUPPORTS, and all other methods are REQUIRED.

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0"> <tx:transaction value="Required" /> <tx:transaction method="get*" value="Supports" /> <tx:transaction bean="noTx" value="Never" /> <tx:transaction bean="someTx" method="get*" value="Mandatory" /> <bean id="requiresNew" class="foo"> <tx:transaction value="RequiresNew"/> </bean> <bean id="noTx" class="foo"/> <bean id="someTx" class="foo"/> <bean id="anotherBean" class="foo"/></blueprint>

Bean level transaction

Bundle wide transactions

JPA Blueprint Integration– JPA Blueprint custom namespace for dependency injection of managed JPA resources

– Managed persistence units (EntityManagerFactory objects) can be injected with or without a JTA Transaction Services implementation.

– Managed persistence contexts (EntityManager objects) are only available with a JTA Transaction services implementation.

– Both managed persistence units and managed persistence contexts behave as per the JPA specification.

– Both jpa:unit & jpa:context can be used as bean constructor argument or bean property

JPA Sample jpa:unit

– Create and close EntityManager in application code (normal return or exception)

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"xmlns:jpa="http://aries.apache.org/xmlns/jpa/v1.0.0"default-activation="lazy"><bean id="persistenceImpl" class="org.apache.aries.samples.blog.persistence.jpa.BlogPersistenceServiceImpl"> <jpa:unit property="entityManagerFactory" unitname="blogExample" /></bean>…

</blueprint>

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"xmlns:jpa="http://aries.apache.org/xmlns/jpa/v1.0.0"default-activation="lazy"><bean id="persistenceImpl" class="org.apache.aries.samples.blog.persistence.jpa.BlogPersistenceServiceImpl"> <property="entityManagerFactory">

<reference interface="javax.persistence.EntityManagerFactory” filter="(&(!(org.apache.aries.jpa.proxy.factory=*))(osgi.unit.name=blogExample))” /> </property>

</bean>…

</blueprint>

JPA Sample jpa:context

– Managed persistence contexts (EntityManager objects) are only available with a JTA Transaction services implementation.

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0"xmlns:jpa="http://aries.apache.org/xmlns/jpa/v1.0.0"default-activation="lazy"><bean id="persistenceImpl" class="org.apache.aries.samples.blog.persistence.jpa.BlogPersistenceServiceImpl"> <tx:transaction method="*" value="Required" /> <jpa:context property="entityManager" unitname="blogExample" /></bean>

</blueprint>

<bean id="persistenceImpl" class="org.apache.aries.samples.blog.persistence.jpa.BlogPersistenceServiceImpl"> <tx:transaction method="*" value="Required" /> <property="entityManager"> <bean factory-ref=“emf” factory-method=“createEntityManager” destory-method=“internalClose” /> </property> </bean>

<reference id=”emf” interface="javax.persistence.EntityManagerFactory” filter="(&(org.apache.aries.jpa.proxy.factory=true)(osgi.unit.name=blogExample))” />

Message Driven Service(MDS)

– Message Driven Service RFP has been approved by OSGi EEG

– Contains requirement for generic OSGi service and additional requirement for blueprint OSGi service.

– Aries provides a prototype work for message driven service.

– A programming model to enable an OSGi service to be a message driven service by using service properties

– Message driven service’s message listener method invokes upon arriving of the message in the destination.

MDS Example

- Example here to illustrate the programming model to define a service as message-driven service.

- It is possible to register service outside of blueprint container

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"> <bean id="myMessageDrivenBean" class="org.apache.aries.mds.sample.MyMessageDrivenBean" destroy-method="destory"> <argument ref="connectionFactory" /> </bean>

<service ref="myMessageDrivenBean" interface="javax.jms.MessageListener"> <service-properties> <!-- state the type of configuration used for the remote service --> <entry key="service.exported.configs" value="org.apache.aries.message.driven" /> <!-- for the activation config properties add the relevant prefix to the property name --> <entry key="org.apache.aries.message.driven.destinationType" value="javax.jms.Queue" /> <entry key="org.apache.aries.message.driven.destination" value="Hello.Queue" /> <!-- transaction attribute based on the tx:transaction element in blueprint --> <entry key="org.apache.aries.message.driven.transactionAttribute" value="Required"/> <!-- service.pid uniquely identifies the service and can be used to bind the service with activation config --> <entry key="service.pid" value="org.apache.aries.mds.sample.myMessageDrivenBean" /> </service-properties> </service> </blueprint>

Bean definition

Service Definition with service properties to identify

Service as MDS

MDS Example using custom namespace

– Leverage Transaction schema.– Valid transaction value: Required or

NotSupported– Provide most configuration via message-

driven element

< blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:md="http://aries.apache.org/xmlns/messagedriven/v1.0.0” xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0" >

<md:message-driven id="myMessageDrivenBean" class="org.apache.aries.mds.sample.MyMessageDrivenBean" destroy-method="destory" scope="singleton" interface="javax.jms.MessageListener"> <tx:transaction method="*" value="Required"/> <md:activationConfig> <md:entry key="destination" value="Hello.Queue" /> <md:entry key="destinationType" value="javax.jms.Queue" /> </md:activationConfig> <md:argument ref="connectionFactory" /> </md:message-driven> …

</blueprint>

Simplify the bean and service Configuration

MDS Impl in Aries

– Code in sandbox currently– Uses message inflow contract defined in

JCA

Aries Blueprint Annotation

– Optional service to the blueprint core

– Rough Prototype, currently only runtime annotation supported.

– Bundle-Blueprint-Annotation manifest header = true if annotation scanning is required

– Class Annotation: @Bean, @Service, @Reference, @ReferenceList

– Method Annotation: @Bind, @Unbind, @Register, @Unregister

– Allow users to annotate the class to define its behavior

– Use common configuration file or config admin to describe the values for the instances (TBD)

Annotation Example 1id is optional

Inject blueprint bundle context

Register Foo as a service

Annotation Example 2

Annotate class as registration listener

Register method for the listener

Unregister method for the listener

Annotation Example 3

Annotate class as reference listener

Inject the service reference

Bind method for the reference listener

Unbind method for the reference listener

Conclusion

– Aries provides many blueprint add-ons to simplify configuration

– Some features are mature while others continue to evolve

– Continue drive standardization

– More blueprint features ahead •Scopes•Security Interceptor?