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 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 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); 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 deļ¬ned 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 bean public class TestBeanImpl { … public void insertRow(String name, int value) throws SQLException { // get the user transaction service UserTransaction ut = getUserTransactionService(); Transaction management & // begin the user transaction application logic ut.begin(); try { // start the operation to insert name, value into the db ... } finally { // commit the user transaction ut.commit(); } } } 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> 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> 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 <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" /> Bundle wide transactions <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 level transaction <bean id="someTx" class="foo"/> <bean id="anotherBean" class="foo"/> </blueprint> – – – – 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. 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 <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> – Create and close EntityManager in application code (normal return or exception) JPA Sample jpa:context <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))” /> – Managed persistence contexts (EntityManager objects) are only available with a JTA Transaction services implementation. 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 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> Service Definition with service properties to identify Service as MDS </blueprint> - 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 MDS Example using custom namespace < blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:md="http://aries.apache.org/xmlns/messagedriven/v1.0.0” Simplify the bean and xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0" > service Configuration <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> – Leverage Transaction schema. – Valid transaction value: Required or NotSupported – Provide most configuration via message-driven element 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 1 id 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?