Dark Planet Development Platform

Quick Start 1: A DPS Application Using the Stub Reference Implementations

Technically, you can run DPS without any API implementations but that's not very interesting. This tutorial shows you how to setup DPS using the stub API implementations, which is only marginally more interesting. Many applications will not require implementations for all the APIs. The stub implementations are an easy way to make sure all the APIs are at least implemented and return something useful (in this case, an UnsupportedOperationException) if someone tries to use an unimplemented part of the API. One you get the stub configuration working, you can replace the stubs with more useful reference implementations (or write your own). If you haven't already, read the pre-requisites tutorial to make sure your Eclipse environment is set up properly.

To get started with the stub implementations, download or checkout the following bundles:

Extract each of these bundles as an Eclipse project. For the "helloworld" bundle, it's best if you extract as a source bundle so you can modify the code as we do in later tutorials.

You can test your installation as follows: In Eclipse, select Run->Run Configurations... You should see "RunHelloWorld" under the "OSGi Framework" section. Select "RunHelloWorld" and click "Run". If all goes well, you should see something like this in the OSGi console:

    EveData registered
    EveDatabase registered
    EveServer registered
    PersistenceFactory registered
    EveMarketData registered
    HelloWorld started!
    IEveDataModel = org.dps.core.impl.model.stub.EveDataModelStub@3b5e234c
    IEveDatabase = org.dps.core.impl.database.stub.EveDatabaseStub@215f7107
    IEveServerRequest = org.dps.core.impl.server.stub.EveServerStub@f593af
    IEvePersistenceFactory = org.dps.core.impl.persist.stub.EvePersistenceFactoryStub@7ab2c6a6
    IEveMarketData = org.dps.core.impl.market.stub.EveMarketStub@236527f
    HelloWorld stopped!

If you see this, then you've successfully run the "Hello, World!" application using the DPS stubs. Here's what's happening under the covers:

The DPS stubs and "Hello, World!" rely on OSGi declarative services to resolve implementations of the DPS core API. You don't have to build DPS applications this way (note that the org.dps.core bundle does not include an OSGI-INF directory). You are free to resolve dependencies any way you like (e.g. bundle dependencies, OSGi registered services, etc). For this example, however, each of the stubs declares which of the core API services it provides, and "Hello, World!" declares the services it depends on. This set of services is exactly the five main core APIs:
Each stub provides one of the five interface implementations above.
When OSGi starts it attempts to resolve bundle dependencies. OSGi loads hibernate and log4j first since they are pre-requisites for every other bundle.
Next, OSGi discovers that "Hello, World!" depends on five services and that each stub bundle implements one or more needed services. OSGi starts each of the stub implementations.
When a stub implementation has started and completed initialization, OSGi passes a reference to the service to component class for "Hello, World!", which is just an instance of the class org.dps.app.helloworld.HelloWorld. This class defines methods to be called when an instance of each of the core API interfaces is available.
When all dependencies of "Hello, World!" have been satisfied, OSGi activates the component by calling HelloWorld.startup(). This method spawns a thread which then runs HelloWorld.run() which in turn displays the startup message and the current value of all the API references.
When the run method completes, then nothing else will happen until you enter a command into the OSGi console. If you enter "close" then OSGi will shutdown your application and terminate the process. When shutdown occurs, OSGi calles HelloWorld.shutdown. This is the method which prints the shutdown message.

The "Hello, World!" application is a useful tool for making sure you're pulling in proper dependencies. Note that you can include the org.dps.app.helloworld bundle any time you like in one of your own applications. OSGi will start the bundle, just like any other bundle, once all of its dependencies have been met.

The "RunHelloWorld" launcher is also a good template to use for your own projects. Some other things you might want to add to this launcher (you can do this by selecting Run->l;Run Configurations... to pull up the launcher editor, or just edit the xml directly):

Add or remove -console to the program arguments. This controls whether an OSGi console appears when you launch.
Add or remove -consoleLog to the program arguments. This controls whether OSGi errors are logged to the console.
Add or remove -Dequinox.ds.print=true to the VM arguments. When true this will show OSGi dynamic services startup errors on the console. This is very useful for debugging dependency resolution problems.
Add or remove -Dosgi.noShutdown=true to the VM arguments. You almost never want to remove this unless you know what you're doing. Equinox is designed to work with Eclipse and will normally shutdown after starting all bundles if it can't find an Eclipse application. This setting tells Equinox to stay running even if it can't find an Eclipse application. This is why the console stays up after "Hello, World!" completes. If you remove this setting, then Equinox will likely shutdown right after your "startup" method completes.
Add or remove -Declipse.ignoreApp=true to the VM arguments. This isn't critical, but when true it tells OSGi to not bother trying to start an Eclipse application. If set to false (or not present), you'll get an innocuous error at startup.

Now what?

The next step is to replace the stub implementations with something more interesting. See the tutorials section for a few examples of adding in the reference implementations.