It has been requested that I release the API that will allow for others to write modules to plug in to the MMOUI Minion tool. While this API will not be finalized until we reach beta, I've decided that it may be beneficial to others to release this API in a pre-release state.
Please note that this API is currently pre-release. It is entirely subject to change. I also make no assertion that the javadocs are 100% written correctly as they have not been reviewed in detail since their initial creation. These reviews will be done before the final release of the API at Beta.
The OSGi Interface
The MMOUI Minion uses an implementation of the OSGi framework known as Apache Felix. Apache has good documentation on how to get started with OSGi
here, but I will go over the absolute basics here for convenience.
Modules are packaged as "bundles." Bundles are simply JAR files which you are likely already familiar with in Java. As with any JAR file, they contain a manifest. OSGi specifies a few extra properties for the manifest which must be specified. Below is the manifest for the WoWInterface module. We will go over it in detail shortly.
Code:
Manifest-Version: 1.0
X-COMMENT: Main-Class will be added automatically by build
Bundle-Name: MMOUI Manager - World of Warcraft
Bundle-Activator: com.mmoui.wow.manager.Main
Bundle-SymbolicName: mmouiwow
Bundle-Version: 2.1.10
Import-Package: org.osgi.framework, javax.swing, javax.swing.table, com.mmoui.manager.services, javax.xml.stream, javax.xml.parsers, org.xml.sax, org.xml.sax.helpers, javax.swing.event
X-Auto-Update-URL: http://some.url/some.xml
This manifest has two additions beyond what you might normally see in a Jar file. Firstly, the green section is specified by OSGi.
- Bundle-Activator - Specifies the one class which will act as the bundle activator for the bundle (we will discuss this momentarily).
- Bundle-SymbolicName - Specifies the name by which this bundle will be identified. All bundles must have a unique name.
- Bundle-Version - Specifies the version number of the module. This will be used for auto-update capabilities which will be discussed later.
- Import-Package - This is a VERY IMPORTANT ONE. Import-Package is how OSGi maintains separation between modules. If you import any packages outside of what is included in this bundle, you MUST specify them here, except for any packages in the java.** namespace. This includes packages such as javax.swing.*. Here's a hint: Every module will have to at least import com.mmoui.manager.services, and probably org.osgi.framework.
You will likely want to review Apache's documentation on Import-Package for more details, because the example provided here is extremely simple. For safety in modules, you will likely want to specify the version numbers of the packages you expect (OSGi allows for multiple versions to be installed and the expected versions will be resolved at run time).
In addition to the standard OSGi manifest properties, we also define an additional property, X-Auto-Update-URL. This optional property allows you to point to a XML file which specifies update trees. The XML schema will be released sometime in the near future, but suffice to say it allows the Minion core to determine if your module has an update and install it accordingly if necessary. This means you literally do not have to code any support in for automatically updating your modules -- you only have to supply the XML feed and the core will handle it for you.
Bundle Activators
Bundle Activators are the "Main" class of OSGi. Instead of providing a "public static void main(String[] args)" like your average Java application, you are required to provide a class which implements the BundleActivator interface. You can find the official documentation from OSGi on BundleActivator
here, but suffice to say, it has two classes: start() and stop(), each of which takes a BundleContext object. Here, you will want to register your services with OSGi so that it can be recognized. You may also wish to do any special initialization steps that would not normally be covered by the initialize() methods available in the API.
The WoWInterface module's BundleActivator.start() is shown below:
Java Code:
/**
* Called by the OSGi framework when this module is installed & activated
* @param context The context in which this bundle operates
* @throws java.lang.Exception If an exception occurs
*/
@Override
public void start
(BundleContext context
) throws Exception { service = new Service();
context.registerService(UpdateService.class.getName(), service, props);
context.registerService(ConfigurationService.class.getName(), service, props);
context.registerService(com.mmoui.manager.services.NewsService.class.getName(),
bundle = context.getBundle();
assert bundle != null;
}
context.registerService() is how your class becomes recognized within OSGi. UpdateService, ConfigurationService, and NewsService are the three services which are provided. We create a new instance of their implementations by this module and then identify their interfaces to OSGi. Take note that a class can implement multiple services simultaneously, as is done here by the "Service" class (please note that this is a different Service than com.mmoui.manager.services.Service -- this is com.mmoui.wow.manager.Service) which implements both ConfigurationService
and UpdateService. OSGi is prepared to handle this case correctly.
The stop() method is less important and mainly used for cleanup. You can unregister your services if you desire, though OSGi will automatically unregister them anyway if you fail to do so.
The Services
There are four major service providers currently available to be implemented:
- UpdateService
- NewsService
- ConfigurationService
- ExtractorFactoryService
UpdateService is the main "updating" capability that can be implemented. It identifies Updatable objects which are then scheduled for updating by the core. If you want to write an updater for any other site, then this is probably where you want to start.
NewsService interfaces with a news panel located on the main UI. This allows for a module to display a panel with news or other information.
ConfigurationService is rarely implemented without at least one of the other services. It offers a UI panel which patches into the configuration screen of the core. This is the best way for modules to allow for users to adjust configuration of the module.
ExtractorFactoryService will generally be implemented alone if it is implemented at all in a bundle. This service allows others to write modules that are capable of extracting various types of files. This permits the system to be able to learn how to extract RAR files, ZIP files, or any other type of file.
Packaging your Module
You have two options for packing up your modules for redistribution. The simplest one is to provide a JAR file. This is the standard format for Java which includes your class files, manifest, and other appropriate items for your module to work. Any user can install a JAR file simply by clicking on the "Install Module" button in the module center.
Your other option is through the use of an archive (such as a ZIP file). There are two restrictions on this type of packaging:
- An ExtractorFactoryService will need to already be installed to be able to handle the file type. Note that this will generally be OK for ZIP files because a ZIP module will be shipped with it.
- Only two folders will be checked for files. Other items will be discarded.
The benefit of using an archive is that you can package additional required external libraries along with your module. The WoWInterface module takes advantage of this feature, as it needs 3 external libraries to operate. You can also ship multiple modules at the same time in the archive.
To create an archive, use the following procedure:
- In the root of your archive, place any main bundles -- that is, the modules themselves.
- In a subfolder of the archive, named "lib" (case-sensitive for some operating systems), place any external libraries required. These libraries MUST be OSGi bundles. Most libraries (especially Apache's) have OSGi versions, and generally those that are not are not difficult to convert to OSGi.
The dependencies between libraries will be computed automatically and loaded in a valid order (though the order is not guaranteed to be consistent if dependencies don't require it). After all libraries have been loaded, the module itself will be loaded.
An example file structure is shown below:
Code:
module.zip
|
+-- myModule.jar
|
|-- lib
| |
| +-- library1.jar
| |
| +-- library2.jar
|
+-- readme.txt
|
+-- docs
|
+-- file1.jar
|
+-- docs.html
The module myModule.jar will be loaded after libraries library1.jar and library2.jar are loaded. The two libraries do not have a definite order here, though dependencies might force the libraries into a particular order. The readme.txt and entire contents of the docs folder are ignored.
Javadocs
Full Javadocs are provided for all of the services. As has already been stated,
everything in the documentation is subject to change without backwards compatibility until beta -- this is PRE-RELEASE INFORMATION.
If you have any suggestions regarding any of the API, please feel free to contact me either here or via private message. I will try to take any requests for changes into account, and will gladly clarify any confusing portion of the documentation.
You can find the current version of the Javadocs for the service interfaces at
http://minion.mmoui.com/javadoc/
04-22-09, 01:47 AM
Linear Mode
