Blueprint Advanced Features Lin Sun Apache Aries and

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, Service References – Bean Interceptors – Declarative Transaction – JPA Blueprint Integration – Message Driven Service – Annotation – Aries. Trader Application Demo – Conclusion

Aries Blueprint Container – Clean implementation based on Blueprint Specification in OSGi Compendium R 4. 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/v 1. 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. Foo. Impl"> <property name="a" value="5" /> </bean> </service> </blueprint> Service manager definition Foo. Impl foo = new Foo. Impl(); foo. set. A(5); Hashtable props = new Hashtable(); props. put(“key”, “value”); bundle. Context. register. Service(org. apache. aries. blueprint. sample. Foo. clas s. get. Name(), foo, props);

Bean Constructor example Account account. One = new Account(1);

Bean Constructor example 2 Account account. Two = Static. Account. Factory. create. Accont(2);

Bean Property example Account account. One = new Account(1); account. One. set. Description(“#1 account”);

Bean Wiring example Account account. One = new Account(); Currency currency = new Currency(); account. One. set. Currency(currency);

Service example Account. Impl account = new Account. Impl(); bundle. Context. register. Service(Account. class. get. Name(), account, new Hashtable());

Reference sample Account. Client account. Client = new Account. Client(); Service. Reference sr = bundle. Context. get. Service. Reference(“org. apache. aries. simple. Account” ); Account account = (Account)bundle. Context. get. Service(sr); account. Client. set. Account(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 Service. Reference 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, Requires. New, Supports, Not. Supported, 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 Test. Bean. Impl { … public void insert. Row(String name, int value) throws SQLException { // get the user transaction service User. Transaction ut = get. User. Transaction. Service(); 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/v 1. 0. 0"> <bean id="Test. Bean. Impl" class="org. apache. aries. simple. Test. Bean. Impl" /> </blueprint>

Simple bean with declarative transaction Focus on application logic public class Test. Bean. Impl { … public void insert. Row(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/v 1. 0. 0" xmlns: tx="http: //aries. apache. org/xmlns/transactions/v 1. 0. 0"> <bean id="Test. Bean. Impl" class="org. apache. aries. simple. Test. Bean. Impl"> <tx: transaction method="insert. Row" 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 R 4. 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/v 1. 0. 0" xmlns: tx="http: //aries. apache. org/xmlns/transactions/v 1. 0. 0"> <tx: transaction value="Required" /> <tx: transaction method="get*" value="Supports" /> Bundle wide transactions <tx: transaction bean="no. Tx" value="Never" /> <tx: transaction bean="some. Tx" method="get*" value="Mandatory" /> <bean id="requires. New" class="foo"> <tx: transaction value="Requires. New"/> </bean> <bean id="no. Tx" class="foo"/> Bean level transaction <bean id="some. Tx" class="foo"/> <bean id="another. Bean" class="foo"/> </blueprint> – For the bean requires. New, all methods have REQUIRESNEW behavior. – For the bean no. Tx, all methods have NEVER behavior. – For the bean some. Tx, methods starting with "get" are MANDATORY, and all other methods are REQUIRED. – For the bean another. Bean, 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 (Entity. Manager. Factory objects) can be injected with or without a JTA Transaction Services implementation. – Managed persistence contexts (Entity. Manager 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/v 1. 0. 0" xmlns: jpa="http: //aries. apache. org/xmlns/jpa/v 1. 0. 0" default-activation="lazy"> <bean id="persistence. Impl" class="org. apache. aries. samples. blog. persistence. jpa. Blog. Persistence. Service. Impl"> <jpa: unit property="entity. Manager. Factory" unitname="blog. Example" /> </bean> … </blueprint> <blueprint xmlns="http: //www. osgi. org/xmlns/blueprint/v 1. 0. 0" xmlns: jpa="http: //aries. apache. org/xmlns/jpa/v 1. 0. 0" default-activation="lazy"> <bean id="persistence. Impl" class="org. apache. aries. samples. blog. persistence. jpa. Blog. Persistence. Service. Impl"> <property="entity. Manager. Factory"> <reference interface="javax. persistence. Entity. Manager. Factory” filter="(&(!(org. apache. aries. jpa. proxy. factory=*))(osgi. unit. name=blog. Example))” /> </property> </bean> … </blueprint> – Create and close Entity. Manager in application code (normal return or exception)

JPA Sample jpa: context <blueprint xmlns="http: //www. osgi. org/xmlns/blueprint/v 1. 0. 0" xmlns: tx="http: //aries. apache. org/xmlns/transactions/v 1. 0. 0" xmlns: jpa="http: //aries. apache. org/xmlns/jpa/v 1. 0. 0" default-activation="lazy"> <bean id="persistence. Impl" class="org. apache. aries. samples. blog. persistence. jpa. Blog. Persistence. Service. Impl"> <tx: transaction method="*" value="Required" /> <jpa: context property="entity. Manager" unitname="blog. Example" /> </bean> </blueprint> <bean id="persistence. Impl" class="org. apache. aries. samples. blog. persistence. jpa. Blog. Persistence. Service. Impl"> <tx: transaction method="*" value="Required" /> <property="entity. Manager"> <bean factory-ref=“emf” factory-method=“create. Entity. Manager” destory-method=“internal. Close” /> </property> </bean> <reference id=”emf” interface="javax. persistence. Entity. Manager. Factory” filter="(&(org. apache. aries. jpa. proxy. factory=true)(osgi. unit. name=blog. Example))” /> – Managed persistence contexts (Entity. Manager 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/v 1. 0. 0"> <bean id="my. Message. Driven. Bean" class="org. apache. aries. mds. sample. My. Message. Driven. Bean" destroy-method="destory"> <argument ref="connection. Factory" /> </bean> <service ref="my. Message. Driven. Bean" interface="javax. jms. Message. Listener"> <service-properties>  <entry key="service. exported. configs" value="org. apache. aries. message. driven" />  <entry key="org. apache. aries. message. driven. destination. Type" value="javax. jms. Queue" /> <entry key="org. apache. aries. message. driven. destination" value="Hello. Queue" />  <entry key="org. apache. aries. message. driven. transaction. Attribute" 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. my. Message. Driven. Bean" /> </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/v 1. 0. 0" xmlns: md="http: //aries. apache. org/xmlns/messagedriven/v 1. 0. 0” Simplify the bean and xmlns: tx="http: //aries. apache. org/xmlns/transactions/v 1. 0. 0" > service Configuration <md: message-driven id="my. Message. Driven. Bean" class="org. apache. aries. mds. sample. My. Message. Driven. Bean" destroy-method="destory" scope="singleton" interface="javax. jms. Message. Listener"> <tx: transaction method="*" value="Required"/> <md: activation. Config> <md: entry key="destination" value="Hello. Queue" /> <md: entry key="destination. Type" value="javax. jms. Queue" /> </md: activation. Config> <md: argument ref="connection. Factory" /> </md: message-driven> … </blueprint> – Leverage Transaction schema. – Valid transaction value: Required or Not. Supported – 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. List – 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?