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