Blueprint Advanced Features

1. 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

2. 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

3. 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.

4. Aries Blueprint Container (cont.) Extender Pattern Blueprint XML Definition files and Metadata

5. Configuration Blueprint xml uses blueprint namspace blueprint ::= <type-converters> manager* manager ::= <bean> | <service> | service reference service-reference ::= <reference> | <reference-list> type-converters ::= <bean> | <ref>

6. 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 top element Blueprint namespace uri <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> Service manager definition

7. Bean Constructor example • Account accountOne = new Account(1);

8. Bean Constructor example 2 • Account accountTwo = StaticAccountFactory.createAccont(2);

9. Bean Property example Account accountOne = new Account(1); accountOne.setDescription(“#1 account”);

10. Bean Wiring example Account accountOne = new Account(); Currency currency = new Currency(); accountOne.setCurrency(currency);

11. Service example AccountImpl account = new AccountImpl(); bundleContext.registerService(Account.class.getName(), account, new Hashtable());

12. 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.

13. 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

14. Advanced Blueprint Features Config Admin Blueprint custom namespace handler Bean Interceptor Declarative Transaction JPA Blueprint Integration Message Driven Service Annotation

15. 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.

16. 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.

17. Simple bean public 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(); } } } Transaction management & application logic Blueprint definition XML for the bean <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"> <bean id="TestBeanImpl" class="org.apache.aries.simple.TestBeanImpl" /> </blueprint>

18. Simple bean with declarative transaction Focus on application logic public class TestBeanImpl { … public void insertRow(String name, int value) throws SQLException { // start the operation to insert name, value into the db ... } } Blueprint definition XML including bean level declarative transaction for the bean <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>

19. 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

20. 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.

21. 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> Bundle wide transactions Bean level transaction

22. 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

23. 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>

24. 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))” />

25. 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.

26. 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 Bean definition <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> Service Definition with service properties to identify Service as MDS

27. 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

28. MDS Impl in Aries Code in sandbox currently Uses message inflow contract defined in JCA

29. 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)

30. Annotation Example 1 id is optional Inject blueprint bundle context Register Foo as a service

31. Annotation Example 2 Annotate class as registration listener Register method for the listener Unregister method for the listener

32. Annotation Example 3 Annotate class as reference listener Inject the service reference Bind method for the reference listener Unbind method for the reference listener

34. 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?