MMOUI Minion API and Documentation (API v2.2.1, Updated 12 May 2009)
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.
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 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:
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.
There are four major service providers currently available to be implemented:
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:
To create an archive, use the following procedure:
An example file structure is shown below:
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
Please note the changes made 29 April 2009 regarding the new PermissionsManager interface which handles security-related requests for modules. See com.mmoui.manager.services.Service.getPermissions() for details on how this is used.
Please note the changes made on May 10, 2009 which adjust the way update services work:
Please see the details of UpdateService, UpdateElement, Updatable, and Uploadable in the com.mmoui.manager.services package for details.
Please note the changes made on May 12, 2009:
In particular, "premium" is no longer something understood by the core. Instead, to hide the ad panel, all currently displayed services need to submit null or a 0-length array for their advertisements. When this occurs, the ad panel will be hidden.
Please note the changes made on May 14, 2009.
All changes should be code-wise backwards compatible. However, the package of the XMLStreamWriter interface has changed (specifically, it has moved from javax.stream.xml to com.mmoui.manager.services). This is due to the fact that this is a J2SE JRE 6 interface. The core and services are now Java 5 compliant, so this interface has been provided to maintain that compatibility. These design of the new interface is intentionally identical to the standard Java 6 one.
|All times are GMT -6. The time now is 12:46 PM.|
vBulletin © 2013, Jelsoft Enterprises Ltd
©2012 ZAM Network LLC