Jaroslav Tulach, author of Practical API design book works in one workshop. He is creating components for other programmers. Lets imagine that he is making nuts and bolts. Of course, his nuts and bolts are more sophisticated, but for sake of argument lets imagine this simple nuts and bolts scenario.

Apparently, his customers are other craftsman and their main requirement is compatibility. They want to use his parts in existing machines, they want to use the same tools they currently have. He just can't decide, that hexagonal head is not modern any more. All his customers have tools for them. Therefore, he has too maintain compatibility. Of course, in some cases he can enhance quality by using better materials, he can introduce better types of components, but once a component is sold to a customer he can't change its dimensions or other important properties. For him backward compatibility and well defined API are crucial. I think that definition for API should be: “Something that is not allowed to change”.

I am on the other hand server-side Java programmer. I write software mainly for end-users. Lets say that I am building custom-made bicycles. You know, some people have so special requirements that they can't go to a shop and just buy a bike. They need special, super-duper tailor made bike.

Usually they do not care what parts I use. They want me to meet their requirements and do it as fast as possible. In this case, I don't care about API at all. I just take existing components and put them together. Of course, I want this components to be well supported, developed in backward compatible way. But me personally, I do not care about creating APIs. I am just using them. Sure, I create my own components, but I do it only because I have to. Sometimes I have to connect two incompatible parts, sometimes there is no-one who makes the part I need. But I always prefer to use already existing parts. I do not know how in bike workshop, but in software there usually is no need to write your own library or new API. Of course, sometimes you are doing something really revolutionary, sometimes your customer requirements are really special, but in my experience, usually customers want something that has already been done hundred times before and there is already someone who makes corresponding parts.

There are only two cases when we have to define an API. The first one is, when we want to reuse custom made components in different projects. It looks like a plausible argument, but I think that in 99% of cases there already is an existing library that already does almost exactly what you need. And I think it is always better to use existing solution then reinvent a wheel.

The other situation where you have to define an API is when you interface with other supplier. For example if your customer wants to mount a rocket launcher on the bike. Then you usually have to agree on some interface between you and the rocket launcher manufacturer. I would bet that there is already a standard for this, but if there is no standard you have to define an API. In my workshop it is usually done using WebServices or other XML based format just because it is easier to change such API in almost compatible way. I usually do not use Java based API just because all the versioning and other issues it brings.

Well, it looks like I do not do anything useful. Hell, I have to defend myself. My added value is that I put those parts together. Customers do not pay me for making bicycle components they pay me for delivering a tandem-tricycles for elephants. That's my job. To build such thing as fast as possible and as cheep as possible. They do not want me to loose their money by reinventing a wheel.

So in my case creating an API is not useful. Sometimes it is even harmful. I'd like to be flexible, I want to be able to fix my mistakes as fast as possible, I'd like to change my design quite often, I do not want to maintain backward compatibility. I do not have to. The only people who will be influenced by my changes are my colleagues. It is quite easy to fix their components accordingly to my changes. At least in software world.

Of course that I try to create well encapsulated and reusable classes. Of course I try to create some kind of communication interface to all my modules. Even for internal usage, I like to have some level of cluelessness. But I would not call it API. It is something one level under API. For me it is just an implementation trick I use to make my life easier. I am not publishing it outside the team, I know that it is not stable at all. It's not an API it's just PI. Of course the distinction is not clear, but I still feel that there is a difference between a stable API and volatile internal PI. Both of them hide implementation details but only API has to be stable.

There are other types of workshops as well. There are for example mass producers. They sell bikes or software in boxes. These people live somewhere in between. They try to use existing parts as much as possible, but they have to differ somehow from their competitors. So they have to provide something special. In this case, there might be a reason to create a special component and make it standard, so they can share this component between teems working on different products. But again, I do not think that they need stable well defined API so much.

There are of course other types of workshops, but my metaphor is slowly reaching its limits so I will abandon it. What I want to say is, that there is no one size fits all approach or advice. What a surprise!

For example, you can read that you should not optimize your code because JVM will do it for you. That's true unless you work for mobile devices. I recommend you to read this, it goes against everything I believe in, yet in their use case it's valid.

There are other examples, I am sure you will come up with your own. The important thing to realize is that there are different worlds for which different approaches apply. So if you do not agree with someone, maybe the reason is that he is from completely different world.


log4j.logger.org.hibernate.SQL=DEBUG
log4j.logger.org.hibernate.type=TRACE


Then you will see everything in your log. For example:


7820 DEBUG [org.hibernate.SQL] {main} - insert into Client (name, personalNumber, id) values (?, ?, ?)
7821 TRACE [org.hibernate.type.StringType] {main} - binding 'John Doe' to parameter: 1
7821 TRACE [org.hibernate.type.StringType] {main} - binding '123X' to parameter: 2
7821 TRACE [org.hibernate.type.LongType] {main} - binding '10' to parameter: 3


public interface DocumentServer {
	/**
	 * Stores a document.
	 * @return document id
	 */
	public String storeDocument(InputStream in);

	/**
	 * Loads document with given id.
	 * @param id
	 * @return
	 */
	public InputStream loadDocument(String id);
}

It works well, until you realize, that you want to call the DocumentServer remotely, for example using Spring HttpInvoker.

HttpInvoker is a nice small tool, that lets you make remote method invocations over HTTP without much pain. It creates dynamic proxy, serializes all attributes using Java serialization, calls remote proxy, which deserializes arguments, calls the implementation and sends the result back in the same way. It is nice, simple and it works without any problem. You can configure it in five minutes. The downside is, that you have to have Spring Java application on both ends of the wire and all arguments that you send over the wire have to be Serializable.

And that's exactly the trouble we have with our DocumentServer. There is no standard InputStream implementation that implements serializable. Lets think about it. We need to have a stream that is able to stream itself into an ObjectOutputStream. Sounds strange, but it is quite easy. We can simply write a wrapper, that implements writeObject(ObjectOutputStream) method and that takes all the bytes from the underlying stream and writes them to the ObjectOutputStream. It is simple and it does not consume much memory.

Deserialization is much harder. We have to implement readObject(ObjectInputStream in) method, load the data and store them somewhere for later use. We can store them in the memory or in a temporary file. If the streams are larger, temporary file is better choice but we have to delete them after use and the implementation gets messy.

The good news is, that we do not have to implement it, it's already done by RMIIO library. They provide SerializableInputStream class that does exactly what we need. You just have to ignore Javadoc comment saying:

An additional layer around a RemoteInputStream which makes it Serializable and an InputStream. In general, this extra layer is not necessary and I do not recommend using this class. However, in the odd case where the callee really wants to get something which is already an InputStream, this class can be useful.

The only thing we have to do is to wrap all the streams into SerializableInputStream like this

new SerializableInputStream(new DirectRemoteInputStream(inputStream));

It can be done by hand written proxy, by dynamically generated proxy or by AOP.

Of course there are other alternatives. The easiest one is to create something like ByteArayInputStream that implements Serializable. If the streams are small enough, it's the best solution.

We can also try to use Hessian, but I had some troubles when method signatures were more complicated. And of course there is still a possibility to implement own remoting mechanism. After all, HTTP is meant to transport streams. But it would require lot of boilerplate code and I do not like boilerplate code.

It is simple to define interceptor in persistence.xml using hibernate.ejb.interceptor property. But it is only possible to specify class name, you can not inject Spring bean. If you read documentation to Spring LocalContainerEntityManagerFactoryBean there is no possibility to specify the interceptor bean there neither. But there is a way how to achieve it. First of all, you have to redefine Hibernate PersistenceProvider.

public class ConfigurableHibernatePersistence extends HibernatePersistence {
	private Interceptor interceptor;
	public Interceptor getInterceptor() {
		return interceptor;
	}

	public void setInterceptor(Interceptor interceptor) {
		this.interceptor = interceptor;
	}

	@SuppressWarnings("unchecked")
	@Override
	public EntityManagerFactory createContainerEntityManagerFactory(PersistenceUnitInfo info, Map map) {
		Ejb3Configuration cfg = new Ejb3Configuration();
		Ejb3Configuration configured = cfg.configure( info, map );
		postprocessConfiguration(info, map, configured);
		return configured != null ? configured.buildEntityManagerFactory() : null;
	}

	@SuppressWarnings("unchecked")
	protected void postprocessConfiguration(PersistenceUnitInfo info, Map map, Ejb3Configuration configured) {
		if (this.interceptor != null)
		{
			if (configured.getInterceptor()==null || EmptyInterceptor.class.equals(configured.getInterceptor().getClass()))
			{
				configured.setInterceptor(this.interceptor);
			}
			else
			{
				throw new IllegalStateException("Hibernate interceptor already set in persistence.xml ("+configured.getInterceptor()+")");
			}
		}
	}
}

(source)

Here we override method createContainerEntityManagerFactory in order to add postprocessConfiguration method call. In this method, it is possible to change Hibernate configuration as needed. Now the only thing to be done is configuring Spring to use our new PersistenceProvider. It is quite simple.

	<bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
		<property name="persistenceUnitName" value="testPU" />
		<property name="dataSource" ref="dataSource" />
		<property name="persistenceProvider">
			<bean class="net.krecan.javacrumbs.jpa.interceptor.ConfigurableHibernatePersistence">
				<property name="interceptor">
					<bean class="net.krecan.javacrumbs.jpa.interceptor.SpringInjectingInterceptor"/>
				</property>
			</bean>
		</property>
	</bean>

And that all folks, we have Spring configured interceptor even when using JPA abstraction. It would be better if similar classes were in Spring or Hibernate, but it's just few lines of code so feel free to copy them if you need to. If you know easier way how to do it, please mention it in the comments below.

I took InterestingPhotos sample application from JavaFX pages and added following code to onNext function (behold, my very first JavaFX code).

try {
	var writer = new FileWriter(new File(System.getProperty("user.home"),"javafx_infection.txt"));
	writer.append("I have escaped the browser. {new Date()}");
	writer.close();
} catch (e:Exception) {
	e.printStackTrace();
}

Now every time user clicks on the “next” button, the applet attempts to write to a file in user home directory. It can be both a malicious code or a legitimate action. There is no way to tell them apart. That's the reason why we need some security mechanism.

Unsigned application
Example
You can choose not to sign the application at all. Usually it is the best choice. This way the application will run in a sandbox and will not be able to execute any potentially dangerous code. On the other hand it will be safe for user to run it and he will not be troubled by any security alert. If the application attempts to execute dangerous code, the JRE will throw a security exception. In our case it will throw

java.security.AccessControlException: access denied (java.util.PropertyPermission user.home read)
at java.security.AccessControlContext.checkPermission(Unknown Source)
at java.security.AccessController.checkPermission(Unknown Source)
at java.lang.SecurityManager.checkPermission(Unknown Source)
at java.lang.SecurityManager.checkPropertyAccess(Unknown Source)
at java.lang.System.getProperty(Unknown Source)
at interesting.Main.hackIt(Main.fx:406)
at interesting.Main.onNext(Main.fx:133)


So if you don't need to do anything dangerous and you are happy to play in the sandbox, unsigned application is the best choice.

Selfsigned application
Example
Most of the samples on JavaFX page are self-signed. It means that the JAR is signed by a certificate that is not verified by any certification authority. In my opinion, that's the worst option you can choose. You force the user to answer following security dialog.

Basically it's the same as executing EXE (or binary) file only more dangerous. Some users already know that they should not execute EXE files from unknown sources, but they don't know that they shouldn't execute Java applications from unknown sources. I am afraid that we will hear about this issue more in the future.

If the user clicks on Run, the application can do whatever it want, if the user clicks on Cancel, the application will not run at all.

Signed application
Example
We can sign the application by a certificate that is validated by a CA. I have used Thawte Freemail Certificate. Sounds trustworthy, doesn't it? If you open the example, you will see following security warning.

It looks less threatening than with the selfsigned certificate. It looks less dangerous. The “Always trust” check-box is even checked by default. But in fact, it's not much safer. It is more complicated to generate such certificate but anyone (even me) can do it. It might be even more dangerous. Everyone who is able to generate a certificate that is validated by the same CA will be allowed to execute the code (if you leave the check box checked). And again, it is all or nothing choice. User can either give the application all permissions or do not run it at all.

Unsigned application with signed JAR
Example
In case you really need to do something potentially dangerous and you do not want to scare the user at the start of the application, you can use signed JAR in an unsigned application. Basically you can put all the dangerous stuff into a jar and sign only this jar. Most of the code can live in the main application which is unsigned. This way the application will start as unsigned and when you attempt to execute the dangerous parts the signed jar will be loaded and the security warning will be shown. In our example the application will start and the security warning will be shown when user clicks on the “next” button. At least that's how it works on my machine. And I like it. This way user can use my application and is notified only when the application needs to do something insecure. And even if he decides that he doesn't trust me, he can still use the application. (This idea came from a guy from Sun, unfortunately I don't remember his name, thanks anyway)

To reiterate, the most secure choice is to write a JavaFX application that does not need any security permissions. If you do not sign it, it runs in the sandbox and everything is fine. If you need to execute some dangerous code, you have to ask user for a permission. Which is good, but users should be instructed that they shouldn't execute any Java(FX) code if they are not sure what it does. So there is a possibility that they will not execute your applications because they will be afraid to do so. I can imagine that in the next versions of JavaFX there will be a signed library provided by Sun that will contain operations that are potentially dangerous but that are in fact safe. Like opening a file using “Open File dialog” etc.

Disclaimer: I am server-side developer, I know nothing about client-side Java, so do not be surprised if something I have written here turns up being wrong. Just correct it in the comments. Thanks.

		Calendar calendar = Calendar.getInstance();
		calendar.clear();
		calendar.set(Calendar.YEAR, 1970);
		calendar.set(Calendar.MONTH, 0);//month is zero based
		calendar.set(Calendar.DAY_OF_MONTH, 1);
		Date date = calendar.getTime();
		System.out.println(date);
		System.out.println(date.getTime());

The command on the line 07 prints out "Thu Jan 01 00:00:00 GMT 1970", the question is what does the command on the line 08 prints? If you are such looser and you do not remember the JavaDoc of java.util.Date class, here is the description of getTime() method.

Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this Date object.

So to reformulate the question, what is the number of milliseconds between January 1, 1970, 00:00:00 GMT and Thu Jan 01 00:00:00 GMT 1970?

What are your guesses? Make yourself famous by adding a comment with correct explanation. And do not worry, if you do not find the solution until tomorrow evening, I will post it here.

 <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
	<property name="locations">
		<list>
			<value>
			  classpath:main-config.properties
			</value>
			<value>
			  file:///${user.home}/spring-test.properties
			</value>
		</list>
	</property>
	<property name="ignoreResourceNotFound" value="true"/>
	<property name="systemPropertiesModeName" value="SYSTEM_PROPERTIES_MODE_OVERRIDE"/>
 </bean>

<bean class="net.krecan.spring.TstBean">
	<property name="property1" value="${property1}"/>
	<property name="property2" value="${property2}"/>
	<property name="property3" value="${property3}"/>
</bean>

Spring tries to load a configuration file from user home directory. If the file is found, properties from the main-config file are overwritten by those found in the spring-test file. And you can even overwrite those by defining a system property with the same name.
I like it. This way every developer can have his own configuration. There is no danger of accidentally committing passwords to a source control system. You can use exactly the same WAR on every environment. It is relatively safe, although some system administrators do not like it. This way you can distribute an application over the internet without forcing users to unpack it, edit a config file and pack it again afterwards.

And of course, the customer did not want to change all their classes just to migrate to Spring. It meant that they needed configure all the beans using Spring, but inject the dependencies directly, not through set methods.

I know that it is ugly and not recommended but in this case I think I have good excuse. It is a customer's requirement. The question of course is how to do it.

You can try to use Spring post-processor. If you register instance of InstantiationAwareBeanPostProcessor you can use method postProcessPropertyValues to manipulate with property values just before Spring attempts to inject them. So you can inject the values into fields by yourself. And it works. The trouble is that you have to do property instantiation and conversion by yourself too. I almost managed to do it when I encountered a big problem - inner beans. In Spring, you can define a bean inside another bean. In order to inject the inner bean to the outer bean, the inner bean has to be already instantiated. But postProcessPropertyValues method is called before inner bean instantiation. So that is a blind alley.

OK, post-processor can not be used, let's do it more hard-core. Spring has something called BeanWrapper. It is used by Spring for setting bean properties. Great, that is the point where I can force Spring to inject into the fields. The only thing I need to do, is to inject my BeanWrapper implementation into Spring. There is only one small trouble. It is not possible to do it. Unsurprisingly, dependency injection does not work inside the dependency injection code. I tried hard, but did not find any simple and safe way how to replace default BeanWrapper implementation. (If you know how to do it, please let me know)

So, if it is not possible to force Spring to inject without set method, let's give him what he is asking for. The final solution is simple. When instantiating beans, I do not instantiate the original class but a subclass that is generated in the runtime and has all needed set methods. For the class generation I use Javassist, it is simple and powerful. To make the integration with Spring as simple as possible, I use factory bean. So the Spring XML config file looks like this

	<bean id="beanFactory" class="net.krecan.beanfactory.SetMethodGeneratingBeanFactory"/>
	<bean id="sampleClass"
		      factory-bean="beanFactory"
		      factory-method="createBean">
		<constructor-arg value="net.krecan.beanfactory.Sample"/>
		<property name="textProperty" value="test.txt"/>
		<property name="intProperty" value="123"/>
		<property name="simpleSample">
			<bean factory-bean="beanFactory"
			   factory-method="createBean">
				<constructor-arg value="net.krecan.beanfactory.SimpleSample"/>
				<property name="textProperty" value="hallo"/>

			</bean>

		</property>
	</bean>

Instead of providing class name in the bean definition, factory-bean attribute is used. Spring than calls method createBean on the factory bean with parameter taken from the constructor-arg element. It contains the class name of the bean. The result of the method call is used as a bean instance and all the properties are set by Spring.

Of course, you do not have to write it this way every time you want to instantiate this kind of bean. Simple custom namespace can be created in order to simplify the syntax.

In the future, when my customer realize that setters are a good thing, the factory can be easily replaced by a dummy implementation.

To reiterate, direct injection of dependencies from XML to the fields without using set methods is not supported by Spring. You can choose between XML based configuration using set methods or annotation based configuration. It is extremely hard to change default Spring behavior. And maybe it is a good thing. So if you need to do ugly XML based field injection, your only choice is to generate set methods in the runtime. Or maybe something else, but I have no idea what.

If you think about it, you realize that UI bundle is exactly the same as the DAO bundle. It only exports a service. In this case it implements DataReceiver interface from the Common bundle. Therefore, pom.xml, generated MANIFEST.MF file and Spring configuration file will be similar to that we have seen in part 1. So I will skip this bundle and jump directly to the Service layer.

In the Service bundle we want to use both DAO and UI. We want to periodically pull the data from the DataLoader and push them to the DataReceiver service.

Let's start with bundle metadata.

	<plugin>
	    <groupId>org.apache.felix</groupId>
	    <artifactId>maven-bundle-plugin</artifactId>
	    <extensions>true</extensions>
	    <configuration>
	    	<instructions>
	    	 <Private-Package>
	    	    net.krecan.spring.osgi.service.*
	    	 </Private-Package>
	    	</instructions>
	    </configuration>
	  </plugin>

This configuration of the Maven OSGi plugin is going to generate following MANIFEST.MF file.


Manifest-Version: 1.0
Bundle-Name: demo-spring-osgi-service
Build-Jdk: 1.5.0_15
Built-By: lukas
Created-By: Apache Maven Bundle Plugin
Private-Package: net.krecan.spring.osgi.service
Import-Package: net.krecan.spring.osgi,org.apache.commons.logging
Bundle-ManifestVersion: 2
Bundle-SymbolicName: net.krecan.spring-osgi.demo-spring-osgi-service
Tool: Bnd-0.0.255
Bnd-LastModified: 1212320410936
Bundle-Version: 1.0.0.SNAPSHOT

You can see that we do not export any package. It is not needed. Service bundle only coordinates DAO and UI, it does not need to expose anything.

Import-Package directive is more interesting. Maven plugin analyzed Java classes and figured out that import of net.krecan.spring.osgi and org.apache.commons.logging package is needed. The first one is exported by our Common bundle, the other one is provided by the commons-logging package. Great, I do not have to specify dependencies by hand, Maven plugin does it automatically.

OK, OSGi is configured, we can try to use our services. Again, I will use Spring OSGi integration. I will create following Spring XML configuration in the META-INF/spring directory of the Service bundle

<?xml version="1.0" encoding="UTF-8"?>
<beans ...>

	<osgi:reference id="dataLoader" interface="net.krecan.spring.osgi.DataLoader"/>

	<osgi:list id="receivers"  interface="net.krecan.spring.osgi.DataReceiver"/>

	<bean id="dataDistributor" class="net.krecan.spring.osgi.service.DataDistributor">
		<property name="dataLoader" ref="dataLoader"/>
		<property name="receivers" ref="receivers"/>
	</bean>

	<!-- Timer config -->
	...	

</beans>

(Full version can be downloade here)

By osgi:reference element we say, that we want to find a service that implements DataLoader service. If such service is running in the OSGi engine, we can use the reference as a Spring bean with ID “dataLoader”. So we can inject it to the dataDistributor bean like any other Spring bean. That is great. The source code is not bound to OSGi at all. If you wish, you can switch form OSGi to a simple deployment, to remote invocation, web service or whatever you want. The source code will remain unchanged. The only thing we need to change is the configuration.

Do you wonder what happens, if there is no DataLoader service running? The answer is simple. Service bundle will wait for it. When DataLoader became available, the Service bundle will start to pull data from it. (This behavior can be changed by the cardinality attribute)

osgi:list element is similar to osgi:reference. It supports multiple references. It implements normal java.util.List. Again, we can inject it to an ordinary Spring bean. Moreover, the list is magic. If new service with given interface appears in the OSGi container, it is automagically added to the list. So I do not have to care about it.

The rest of the Spring config is not connected with OSGi. It just starts timer job that calls dataDistributor.loadAndSend method every 100ms.

And now we can test it. We will again use Spring OSGi support for integration tests. First of all, we have to say which bundles we are going to use.

	protected String[] getTestBundlesNames() {
		return new String[] {
			"net.krecan.spring-osgi, demo-spring-osgi-dao, "+DEMO_VERSION,
			"net.krecan.spring-osgi, demo-spring-osgi-ui, "+DEMO_VERSION,
			"net.krecan.spring-osgi, demo-spring-osgi-service, "+DEMO_VERSION,
		};
	}

And now we can run the test.

	public void testAddUi() throws InterruptedException, BundleException, IOException
	{
		Thread.sleep(500);
		LOG.info("Starting alternative UI");
		Resource bundleResource = locateBundle("net.krecan.spring-osgi, demo-spring-osgi-ui-alternative, "+DEMO_VERSION);
		Bundle bundle = bundleContext.installBundle(bundleResource.getURL().toString());
		bundle.start();
		LOG.info("Alternative UI started");
		Thread.sleep(500);
		LOG.info("Stopping alternative UI");
		bundle.stop();
		LOG.info("Alternative UI stopped");
		Thread.sleep(500);

	}

To make it more interesting, we will run the test for 500ms and then we will add and start alternative UI bundle. After another 500ms we will stop the alternative UI bundle again. It will result into following log output.

It looks exactly how it should. Messages from the alternative UI appear and then disappear together with corresponding bundle. That's what OSGi is all about. It enables dynamic binding of components. We can replace or plug-in services dynamically in the runtime.

To reiterate. Today we have seen OSGi in action. We have connected several services using Spring support and we have seen dynamic nature of OSGi. And what's the best, our source code is not aware of OSGi. What a nice example of dependency injection.

Next time, we will try to play a bit with the example. I want to run it standalone, without Spring integration testing support and I'd like to test how it is resistant to class loader leaks.

Source code is accessible in here.

In programming every problem can be solved by adding another layer of abstraction

Today, I am going to write about my experiments with OSGi. Please, be aware that I do not know OSGi. Moreover, I am too lazy to learn it. But I know Spring and Maven quite well, so I will use them quite extensively.

I will try to implement following sample application

We will have 5 bundles in total. Bundle is basic building block when working with OSGi applications. Please, read the OSGi documentation for more details.

We will have the Common bundle, which is quite simple passive bundle. It contains DataLoader and DataReceiver interfaces and Data object. This bundle does not provide any service, but every other bundle has compile-time dependency on it.

DAO bundle provides DataLoader service implementation. Please, imagine that there is some really cool data access logic.

UI bundle provides DataReciver service implementation. Again, we will pretend that there is something more sophisticated than printing to the console. To make the example more interesting, we will have two different implementations of the UI.

And in the middle of the application sits Service bundle that loads data from the DAO layer and propagates them to the UI layer.

Before diving into the code, I want to point out one interesting thing. If you look at the picture, you will see red and black arrows. Black arrows represent compile-time dependencies. Basically it means, that when I want to compile UI, Service and DAO, I have to have Common jar in the classpath. But I do not need to have there any other bundle. It means, that the bundles are really decoupled. They just do not need to know about each other. They are independent. Do you understand? That's the modularity we are looking for. The only thing the bundle needs to know is the interface of the service. Did I already mention that the bundles are independent? If not, I am saying it right know. They are independent.

The red arrows are run-time dependencies. That's what OSGi framework is for. It will find for us the implementations of the interfaces (services) and will connect them together.

DAO service

So lets dive to the code. We will start with the DAO service. OSGi uses MANIFEST.MF file for defining its meta-data. Since I am to lazy to write it, I will use Maven plugin to generate it for me.

<plugin>
	<groupId>org.apache.felix</groupId>
	<artifactId>maven-bundle-plugin</artifactId>
	<extensions>true</extensions>
	<configuration>
		<instructions>
		 <Export-Package>
		 	net.krecan.spring.osgi
		 </Export-Package>
		 <Private-Package>
		 	net.krecan.spring.osgi.*
		 </Private-Package>
		</instructions>
	</configuration>
</plugin>

As you can see, I am using Apache Felix plugin for Maven. It generates following MANIFEST.MF file for me.


Manifest-Version: 1.0
Export-Package: net.krecan.spring.osgi
Private-Package: net.krecan.spring.osgi.dao
Built-By: krel
Tool: Bnd-0.0.255
Bundle-Name: demo-spring-osgi-dao
Created-By: Apache Maven Bundle Plugin
Bundle-Version: 1.0.0.SNAPSHOT
Build-Jdk: 1.6.0_03
Bnd-LastModified: 1211919191482
Bundle-ManifestVersion: 2
Import-Package: net.krecan.spring.osgi
Bundle-SymbolicName: net.krecan.spring-osgi.demo-spring-osgi-dao


It says that I am importing package net.krecan.spring.osgi. That's the package where the interfaces are defined in. And I am exporting this package again, since I am publishing implementation of one of the interfaces. (Well, I am not sure if its true, but it did not work, when this package was not exported.) All other packages are private. It means, that they can not be used be other bundles. Wow, it is something like Java 7 superpackages.

Ok, OSGi is almost configured, the only think we need to do is to define the service. But again, I am to lazy to learn OSGi. What to do? What about Spring?. Spring provides support for OSGi. So I can export whatever Spring bean I want as an OSGi service. The only think I have to do, is to put following XML file into META-INF/spring directory.

<?xml version="1.0" encoding="UTF-8"?>
<beans ...>

	<osgi:service ref="dataLoader"
		interface="net.krecan.spring.osgi.DataLoader" />

	<bean id="dataLoader"
		class="net.krecan.spring.osgi.dao.DefaultDataLoader" />
</beans>

(Full version can be downloade here)

I am publishing dataLoader bean as an implementation of DataLoader interface. Later on, when some other bundle will look for the service, it will just say, that it wants implementation of this interface and OSGi will find it.
And that's it. I have created my first OSGi bundle. What? You do not believe that it works? Ok, I will test it using Spring OSGi testing support. We will write simple integration test.

package net.krecan.spring.osgi.dao;

import net.krecan.spring.osgi.DataLoader;

import org.osgi.framework.ServiceReference;
import org.springframework.osgi.test.AbstractConfigurableBundleCreatorTests;
import org.springframework.osgi.test.platform.Platforms;

/**
 * Tests the DAO bundle.
 * @author Lukas Krecan
 *
 */
public class DaoOsgiTest extends AbstractConfigurableBundleCreatorTests {

private static final String DEMO_VERSION = "1.0-SNAPSHOT";

	protected String getPlatformName() {
		   return Platforms.FELIX;
	}

	protected String[] getTestBundlesNames() {
		return new String[] {
			"net.krecan.spring-osgi, demo-spring-osgi-dao, "+DEMO_VERSION,
		};
	}

	/**
	 * The superclass provides us access to the root bundle
	 * context via the 'getBundleContext' operation
	 */
	public void testOSGiStartedOk() {
		assertNotNull(bundleContext);
	}

	public void testGetDataLoader() throws Exception {
		ServiceReference ref = bundleContext.getServiceReference(DataLoader.class.getName());
        assertNotNull("Service Reference is null", ref);
        try {
        	DataLoader dataLoader = (DataLoader) bundleContext.getService(ref);
            assertNotNull("Cannot find the service", dataLoader);
            assertNotNull("Data are null", dataLoader.loadData());
        } finally {
            bundleContext.ungetService(ref);
        }
	}
}

The test extends AbstractConfigurableBundleCreatorTests which takes care of starting OSGi engine (Apache Felix in this case) and loading all necessary bundles. The only think we have to specify is the name of the bundle under test. (The test loads the bundles from the local Maven repository by default.) We can than test whether the bundle is started and the service is running.

That's all for today, in the next part we will discuss UI bundle and the service bundle. I will be glad for any feedback, so if you will spot any mistake in the text, please let me know. Of course I accept the compliments as well.

Source code is accessible in here.