Dark Planet Development Platform

Quick Start 3: Add the EVE Server Data Reference Implementation

This tutorial takes the setup you created in the previous quick start tutorials and replaces the stub for the EVE server data API with the DPS reference implementation. Don't worry if you didn't read any of the other tutorials, we'll repeat the key steps here. You do, however, need to have your Eclipse environment set up as described here.

First, either download or checkout all the stubs and the EVE server data reference implementation. If you've already set up the static data reference implementation then you can skip downloading the stub. Likewise, if you've already downloaded the "Hello, World!" application you don't need to do that again:

Core and Stubs:
The "Hello, World!" example app:
- org.dps.app.helloworld
The IEveServerRequest DPS reference implementation:
- org.dps.core.impl.server.eveapi

If you're extracting the helloworld bundle for the first time, make sure you extract it as a source bundle as we'll need to modify it below. If you've already extracted it as a binary bundle then just delete it and re-extract as a source bundle.

Now we'll add some simple code to retrieve the character sheet for one of our characters. In order for this to work, you'll need to create a "customizable API key" for one of your characters which allows requests for the private character sheet. The EVE support page is where you need to go to create a key. When creating a key, make sure you check "CharacterSheet" in the "Private Information" section.

Once you have a key created, modify the run method in org.dps.app.helloworld.HelloWorld so it looks like this:

	public void run() {
		System.out.println("HelloWorld started!");

		System.out.println("IEveDataModel = " + eveRef);
		System.out.println("IEveDatabase = " + eveDB);
		System.out.println("IEveServerRequest = " + eveServer);
		System.out.println("IEvePersistenceFactory = " + evePersistence);
		System.out.println("IEveMarketData = " + eveMarketData);

                // If you read quickstart 2 then you probably have
                // database access code here.  You can leave it.

                // Create a server access handle, get our character sheet, and print it.
                int keyID = ...your key ID...
                String vCode = ...your vCode...
                long charID = ...your character ID...
                ICharacterAPIRequest charRequestor = eveServer.getCharacterAPIService(keyID, vCode, charID);

                try {
                        ICharacterSheet charSheet = charRequestor.requestCharacterSheet();
                        if (!charRequestor.isError())
                               System.out.println("CharacterSheet:\n" + charSheet);
                        else
                               System.out.println("Unable to get CharacterSheet with error: " + charRequestor.getErrorString());            } catch (Exception e) {
                        System.out.println("Unable to get CharacterSheet with error: " + e);
                }
	}

If you read the first Quick Start tutorial, you know that on startup OSGi will resolve all our bundle dependencies and make sure that we have a valid reference for things like IEveServerRequest. You also know, however, that the default launch configuration RunHelloWorld.launch pulls in the stub applications. We need to fix this before running our code which means we need to change our launch configuration. Rather than mangle our existing launch configuration, you should create a new one, or use the one you created in "quick start 2" if you read that tutorial. To make our configuration work we just need to replace the EVE server stub bundle with the reference implementation bundle:

Select the "Bundles" tab.
Uncheck "Only show selected" on the right.
Find the bundle "org.dps.core.impl.server.stub" and uncheck it.
Find and check the bundle "org.dps.core.impl.server.eveapi".
Check your work by clicking "Validate Bundles" on the right.

If "Validate Bundles" passes then you can check "Only show selected" again if you like.

Now click "Apply", then "Run". You should see something like this:

    EveData registered
    EveDatabase registered
    EveServer registered
    PersistenceFactory registered
    EveExtension registered
    EveMarketData registered
    HelloWorld started!
    IEveDataModel = org.dps.core.impl.model.stub.EveDataModelStub@20e183e9
    IEveDatabase = org.dps.core.impl.database.stub.EveDatabaseStub@2cf18e8e
    IEveServerRequest = org.dps.core.impl.server.eveapi.EveAPIServerRequestAdapter@26c623af
    IEvePersistenceFactory = org.dps.core.impl.persist.stub.EvePersistenceFactoryStub@2830ae41
    IEveExtension = org.dps.core.impl.extension.stub.EveExtensionStub@14004204
    IEveMarketData = org.dps.core.impl.market.stub.EveMarketStub@1cee1ede

    ... xml dump of a character sheet ...

If you see this, then you've successfully run the "Hello, World!" application using the DPS IEveServerRequest reference implementation.

Under the Covers

Just like in the other Quick Start tutorials, OSGi is resolving bundles and passing the resolved bundle references to our startup application via the "register" methods we've created. This time around, instead of using the server stub, we're using the reference implementation which can actually make API calls to the EVE API server.

The server reference implementation is not a clean sheet implementation. Instead, we make use of EveApi which is a third party Java library for making server calls. EveApi has most of the functionality we want but is also missing some things. So the reference implementation includes some code to fill in the gaps. The majority of the reference implementation consists of wrappers which adapt EveApi to the DPS core interfaces. This is one of the benefits of the DPS approach: the core APIs are general enough that it is easy to adapt existing third party libraries for use in DPS apps. In fact, this was one of the design goals from the start as we didn't want to have to re-implement where many good existing libraries already exist.

You can get a more detailed description of the server data reference implementation in the "Reference Implementations" section on the main page.