Pentagaia toolbox - Start

The start library contains helper classes to startup and customize the Project Darkstar kernel. This is used for multiple libraries that require some kind of lifecycle management and class loading features.

Installation

You can use maven to download and install this module. Add the repository linked in this website's menu to find the modules. You will need one of the following modules depending on the version you are using:

  • start-0_9_5_1
  • start-0_9_6

    Maven will manage dependencies. if you are installing manually you will need the following module jar:

  • start-api

    To run and use this module add the jars to your bootstrap jar. This will enable kernel customization. Use the alternative main class com.pentagaia.tb.start.Main . Simply invoke it with one command line parameter that identifies your application.properties file. For detailed description see the pds docs and examples.

    Note:
    This module currently breaks down security. You should not use it on productional servers of with security managers. There will be a more secure version in the future that contains some policy files too.

Configuration

You can define properties as standard java properties, within the pds configuration file (property com.sun.sgs.config.file ) introduced in pds version 0.9.5.1 or within your application.properties file. Similar to version 0.9.5.1 the kernel will use the following order to find a property: * application.properties * system properties * pds configuration file

Note:
The original pds kernel 0.9.5.1 allows multiple applications to be started with one kernel. The start project will deny this because multiple application configuration is removed in newer kernel versions.
Note:
The original pds kernel 0.9.6 does not use the pds configuration any more. However the start project respects this file and will load it's properties like in 0.9.5.1. But the pds configuration file became optional.

com.pentagaia.tb.start.Boot.Path

A set of paths that will be loaded as class path entries. The paths will be separated by PATH_SEPARATOR . The bootup method will try to load this entries to access additional jar files. If you provide a directory the bootup method will try to search for jar/zip files recurse in this directory. Example:

/var/lib/pds/myplugins:/var/lib/pds/globalplugins/sample.jar

com.pentagaia.tb.start.Secured.Providers

If this property is not set we allow every class to customize/hack the kernel. However this might be unsafe in non-development environments. List classes separated by semicolon to allow only the specified kernel hacks. See below for a detailed information on providers.

The bootup process

After starting the main class it will try to read the properties from command line options and the pds configuration file. After reading them there will be an instance of IStartupConfiguration . You may create your own instance if you are planning to write your own main class. This interface returns some useful information to start the pds kernel. And it returns the property sets of the started application.

The KernelManager class helps us to create a custom class loader and a kernel instance. It manages the hacks and provides access to the standard kernel. You may invoke this Class by yourself if you are not using the original main class.

You may even create several independent kernels. Every kernel will automatically be located in his own class loader instance so that it does not influence another kernel instance. But have a look to not give the same properties to multiple kernel instances. A kernel must not be run on the same data store than another kernel. It will break down the bdb database.

How to use the kernel

Whenever you are developing code that is intended to be run inside the pds gameserver (f.e. an application listener or a service) you can access the current kernel by calling static method KernelManager.getKernel() . See the IPdsKernel interface for more details.

Most of the methods will allow the kernel customizations. But you are only allowed to invoke them during the startup phase. To customize the kernel in the startup phase you will have to install a pds kernel provider . That's an interface installed via sun's manifest services. For details have a look at the sun jar file specification or download the start-api-tests.jar from pentagaia repository. You will find a small file inside folder /META-INF/service .

After packing your jar file you will only need to add this to the bootstrap jar or to the folders specified by property com.pentagaia.tb.start.Boot.Path . If you want to select only a few providers you should define property com.pentagaia.tb.start.Secured.Providers .