Managed Object

From EsWiki

A managed object is an ideal way for an extension to track data over time and share it between plugins and event handlers. Any plugin in the same extension can access the managed object, invoking methods on it to store and retrieve data. This managed object is not available to plugins in a different extension however. Managed object factories are not accessible across extensions because they return raw objects rather then safer objects (like EsObject). If your project requires plugins in different extensions to share data, you will need to use interop, user variables, user server variables, or persist the data to a file or database.

Contents 1 Managed Object Factory 1.1 acquireObject 1.2 releaseObject 2 Extension.xml 3 Acquiring the Managed Object 4 Usages

Managed Object Factory

Create a Java class that implements ManagedObjectFactory and ManagedObjectFactoryLifeCycle. The life cycle works the same way that a plugin's life cycle works, so you can use the init method to read parameters from Extension.xml and to initialize any variables. There will be a single instance of this class on the ES4, and normally a single instance of the managed object it creates. The parts that differ from plugins are:

• acquireObject
• releaseObject

acquireObject

This is the method that returns the actual managed object. The EsObjectRO parameter is often ignored completely, however if your managed object factory includes several different managed objects you may use the parameter to specify which one is to be returned.

releaseObject

One use of a managed object is for a connection pool. In this case, when a plugin no longer needs the connection, it needs to release the managed object, which will then release the connection so that some other plugin can use it. If your managed object is just storing data, then this method can be left empty.

Extension.xml

Extension.xml will include a node in the ManagedObjects section that specifies the managed object factory class for this managed object, in the same way that plugins are specified. The following example shows a managed object factory that has an initialization variable.

<Extension>
      <Name>ExampleExtension</Name>
      <ManagedObjects>
        <ManagedObject>
            <Handle>ControllerFactory</Handle>
            <Type>Java</Type>
            <Path>com.mypackage.ControllerFactory</Path>
            <Variables>
                <Variable name="propertiesFileName" type="string">controller.properties</Variable>
            </Variables>
        </ManagedObject>
      </ManagedObjects>
      <EventHandlers>
            <LoginHandlers>
                  <LoginHandler>…</LoginHandler>
            </LoginHandlers>
            <LogoutHandlers>
                  <LogoutHandler>…</LogoutHandler>
            </LogoutHandlers>
      </EventHandlers>
      <Plugins>
            <Plugin>…</Plugin>
      </Plugins>
</Extension>

Acquiring the Managed Object

Any plugin can use getApi().acquireManagedObject to get the managed object. Let's use the above example, and assume that the ControllerFactory is handling a Controller object. A plugin needing to access that object would use code similar to this:

        Controller controller = (Controller) getApi().acquireManagedObject( "ControllerFactory", null );

Frequently plugins will have class variables for managed objects, so that they only need to acquire them a single time. If the managed object factory's acquireObject method actually uses the EsObjectRO parameter, then the null in the code above would need to be an EsObject or EsObjectRO. Once the controller object is acquired, any public method can be invoked on it, such as getters, setters, and more complicated methods.

After the managed object is no longer needed, it may be released using code similar to this:

        getApi().releaseManagedObject("ControllerFactory", controller);

This invokes the managed object factory's releaseObject method, which should release any locks.

Usages

Here are a few examples of usages of managed objects:

• Connection pool to a database
• Logging chat by room
• Separate thread pool for service calls
• Data read from a file or database and cached in the ES4's memory
• Data about users who are not currently logged in, such as users who have been banned from the ES4 for a short time (no point in persisting this to a database when it's just for an hour or so)