multiverse.server.engine
Class EnginePlugin

java.lang.Object
  multiverse.server.engine.EnginePlugin

All Implemented Interfaces:

MessageCallback, StatusMapCallback

Direct Known Subclasses:

ClassAbilityPlugin, CombatPlugin, GroupPlugin, InstancePlugin, InventoryPlugin, JukeboxWebPlugin, LoginPlugin, MobManagerPlugin, ObjectManagerPlugin, ProxyPlugin, QuestPlugin, TrainerPlugin, VoicePlugin, WorldManagerPlugin

public class EnginePlugin
extends Object
implements MessageCallback, StatusMapCallback

The EnginePlugin is the preferred way to extend the server. Sub-class to add new server functionality. Plugins typically implement one or more sub-objects, identified by name space. The sub-class provides its own hooks for sub-object manipulation; creation, load, unload, delete, and custom operations.

Plugins must have a unique name. This identifies the plugin within the messages domain/cluster. The plugin name should be set in the plugin constructor. setName(String) Plugins must have a plugin type. The plugin type is a string associated with a plugin class. The plugin type is used to resolve startup dependencies. The plugin type should be set in the plugin constructor. setPluginType(String)

When the multiverse engine starts up, it will load initialization scripts (which can change the network ports and database server, etc) and then bring up the database and network services.

After these services are up, the engine loads the remaining game scripts. These scripts will register engine plugins, by calling Engine.registerPlugin(String classFile). This is where the plugin object is constructed.

The engine then calls the activate method on all registered plugins. You can call Engine.getPlugin(String pluginName) to retrieve a registered plugin.

See Also:

HookManager

Nested Class Summary

static interface	EnginePlugin.DeleteHook The interface definition to be satisfied by delete hook objects, containing the onDelete method.
static class	EnginePlugin.DeleteSubObjHook
(package private) class	EnginePlugin.DumpAllStacksMessageHook
static class	EnginePlugin.GenerateSubObjectHook A hook to process the GenerateSubObjectMessage, sent by the object manager.
(package private) class	EnginePlugin.GetPropertyHook A hook called whenever a GetPropertyMessage is received.
static class	EnginePlugin.GetPropertyMessage Get property message for an sub object in a particular namespace.
static interface	EnginePlugin.LoadHook The interface definition to be satisfied by load hook objects, containing the onLoad method.
static class	EnginePlugin.LoadSubObjHook A hook called to load sub-object.
static interface	EnginePlugin.PluginActivateHook
static class	EnginePlugin.PluginStateMessage Message used by plugins to announce various control states.
(package private) class	EnginePlugin.PluginStateMessageHook processing plugin status message - used internally by the EnginePlugin.
(package private) class	EnginePlugin.PoolMessageHandler This class uses an Executor thread pool to process QueuedMessage instances.
(package private) class	EnginePlugin.QueuedMessage A Runnable utility class used to handle callbacks that require a thread pool because it takes a long time or blocks.
static interface	EnginePlugin.SaveHook The interface definition to be satisfied by save hook objects, containing the onSave method.
static class	EnginePlugin.SaveSubObjHook A hook called to persist a sub-object.
(package private) class	EnginePlugin.SetPropertyHook A hook called whenever a SetPropertyMessage is received.
static class	EnginePlugin.SetPropertyMessage Set property message for an sub object in a particular namespace.
static class	EnginePlugin.SubObjData Returned by GenerateSubObject hook's generateSubObject() method.
(package private) class	EnginePlugin.SubObjectDepsReadyHook The object manager is telling us that all dependencies for the sub object are done.
(package private) class	EnginePlugin.SubPersistenceHook The object manager plugin received a setPersistence message and it sent out a SubPersistenceMessage to each namespace in the master object.
static class	EnginePlugin.TransferFilter Base class for message filters used for the transfer object subscription.
static class	EnginePlugin.TransferObjectMessage The message used to transfer control of an object from one world manager to another.
static interface	EnginePlugin.UnloadHook The interface definition to be satisfied by unload hook objects, containing the onUnload method.
static class	EnginePlugin.UnloadSubObjHook

Field Summary

private LinkedList<EnginePlugin.PluginActivateHook>	activateHookList
private Map<Namespace,EnginePlugin.DeleteHook>	deleteHookMap
protected static Long	deleteSubObjectSubscription
private Lock	depLock A lock serializing access to depsOutstanding collection.
(package private) Map<Long,Map<Namespace,Hook>>	depsOutstanding Add the list of namespaces paired with the hook to call to the list of outstanding dependencies for the oid.
protected static Long	dumpAllThreadSubscription
protected static Lock	dumpAllThreadSubscriptionLock
(package private) MVMeter	engPluginMeter
private HookManager	hookManager
private Map<Namespace,EnginePlugin.LoadHook>	loadHookMap
protected static Long	loadSubObjectSubscription
(package private) Collection<Namespace>	localNamespaces A collection of Namespace objects associated with the plugin, initialized by the call to EnginePlugin.registerPluginNamespaces().
protected Lock	lock
private MessageCallback	messageHandler
static MessageType	MSG_TYPE_DUMP_ALL_THREAD_STACKS Message from proxy server, telling all processes to dump their thread stacks to the log.
static MessageType	MSG_TYPE_GET_PROPERTY
static MessageType	MSG_TYPE_PLUGIN_STATE
static MessageType	MSG_TYPE_SET_PROPERTY
static MessageType	MSG_TYPE_SET_PROPERTY_NONBLOCK
static MessageType	MSG_TYPE_TRANSFER_OBJECT Message requesting transfer of an entity to a different world manager.
private String	name
private ObjectLockManager	objLockManager
private int	percentCPULoad
private boolean	pluginAvailable
private String	pluginInfo
(package private) String	pluginState THIS plugin's state
private Map<String,String>	pluginStateMap
protected static Long	pluginStateSubscription
private String	pluginType
protected static Long	propertySubscription
protected static Long	saveSubObjectSubscription
protected static INamespaceFilter	selectionFilter
protected static Long	selectionSubscription
protected static Long	setSubObjectPersistenceSubscription
private Long	subObjectDepReadySub Subscription for the object manager plugin SubObjectDepsReady message.
protected static Long	subObjectSubscription
private Map<Namespace,EnginePlugin.UnloadHook>	unloadHookMap
protected static Long	unloadSubObjectSubscription

Fields inherited from interface multiverse.msgsys.MessageCallback

NO_FLAGS, RESPONSE_EXPECTED

Constructor Summary

EnginePlugin()
No args constructor (deprecated).

EnginePlugin(String name)
constructor.

EnginePlugin(String name, EnginePlugin.PluginActivateHook activateHook)
constructor.

Method Summary

void	activate() called by the engine to initialize the plugin.
private void	addToDepsOutstanding(Long oid, Namespace namespace, Hook callback) Associates the oid/namespace pair with the callbacks in the depsOutstanding map.
private void	createManagementObject()
protected Object	createMBeanInstance()
void	createSubscription(Hook hook, MessageType msgType, int flags) helper method to create a subscription based on a message type and associate it with a hook for processing.
HookManager	getHookManager() Returns the HookManager associated with this plugin.
protected MessageCallback	getMessageHandler()
String	getName() Returns the name of the plugin.
protected ObjectLockManager	getObjectLockManager() Returns the ObjectLockManager associated with this plugin.
static List<Serializable>	getObjectProperties(Long oid, Namespace namespace, List<String> keys) EnginePlugin entrypoint which gets a list of the values of the object properties associated with the given list of keys
static List<Serializable>	getObjectProperties(Long oid, Namespace namespace, String... keys) EnginePlugin entrypoint which gets a list of the values of the object properties associated with the list of keys supplied as varargs
static Serializable	getObjectProperty(Long oid, Namespace namespace, String key) EnginePlugin entrypoint which gets the value of the object property associated with the given key
int	getPercentCPULoad() Getter for percentCPULoad.
boolean	getPluginAvailable()
String	getPluginInfo() Getter for pluginInfo.
Collection<Namespace>	getPluginNamespaces()
String	getPluginState(String pluginName) See EnginePlugin.PluginStateMessage.BuiltInState for some possible values
String	getPluginStatus() Return the status string for the plugin
String	getPluginType() Getter for pluginType.
protected boolean	getPropertyImpl(EnginePlugin.GetPropertyMessage msg) Process the GetPropertyMessage, looking up the entity by oid and namespace, and getting the properties identified by the list of keys in the message.
Map<String,String>	getStatusMap() Override to provide plugin status.
void	handleMessage(Message msg, int flags) Callback method for subscriptions which by default calls hooks registered with this plugin's hookmanager via EnginePlugin.getHookManager().
protected void	handleMessageImpl(Message msg, int flags) Iterate through the Hooks associated with the message type, calling each one's processMessage() method until one of them returns false.
protected void	logDepsOutstanding(String prefix, Long oid, Namespace ns) A utility method to log depsOutstanding for the given oid
void	onActivate() for developers extending the EnginePlugin object, it may be easier to use the onActivate() method which gets called when the plugin is being activated by the Engine.
protected static Map<String,Serializable>	processKeysAndValues(String what, Serializable[] keysAndValues) A utility function to turn an array of keys and values into a propMap.
void	registerActivateHook(EnginePlugin.PluginActivateHook hook) Called on startup to initialize the plugin.
void	registerDeleteHook(Namespace namespace, EnginePlugin.DeleteHook deleteHook) Register a hook to be called when one of this plugin's sub object instances is deleted.
void	registerLoadHook(Namespace namespace, EnginePlugin.LoadHook loadHook) Register a hook to be called when one of this plugin's sub object instances is loaded.
void	registerPluginNamespace(Namespace namespace, EnginePlugin.GenerateSubObjectHook genSubObjHook) Register the plugin namespace, used to identify the kind of subobject created by this plugin.
void	registerPluginNamespaces(Collection<Namespace> namespaces, EnginePlugin.GenerateSubObjectHook genSubObjHook) Register plugin namespaces, used to identify the kind of subobject created by this plugin.
void	registerPluginNamespaces(Collection<Namespace> namespaces, EnginePlugin.GenerateSubObjectHook genSubObjHook, Hook loadSubObjHook, Hook saveSubObjHook, Hook unloadSubObjHook, Hook deleteSubObjHook, INamespaceFilter selectionFilter, INamespaceFilter subObjectFilter) Register namespaces this plugin is authoritative for.
void	registerPluginNamespaces(Collection<Namespace> namespaces, EnginePlugin.GenerateSubObjectHook genSubObjHook, INamespaceFilter selectionFilter, INamespaceFilter subObjectFilter) Register plugin namespaces, used to identify the kind of subobject created by this plugin.
void	registerSaveHook(Namespace namespace, EnginePlugin.SaveHook saveHook) Register a hook to be called when one of this plugin's sub object instances is saved.
void	registerTransferHook(Filter filter, Hook hook) Creates a subscription for transfer messages.
void	registerUnloadHook(Namespace namespace, EnginePlugin.UnloadHook unloadHook) Register a hook to be called when one of this plugin's sub object instances is unloaded.
private Hook	removeFromDepsOutstanding(Long oid, Namespace namespace) Removes the oid/namespace pair from the depsOutstanding map.
void	sendSubObjectResponse(Message origMsg, Long oid, Namespace oidNamespace) Overloading of sendSubObjectResponse used when there are no dependent Namespaces
void	sendSubObjectResponse(Message msg, Long oid, Namespace oidNamespace, LinkedList<Namespace> depNamespaces, Hook callback) The plugin calls this after generating a sub object to let the object manager know the sub object is ready.
void	sendSubObjectResponse(Message origMsg, Long oid, Namespace oidNamespace, Namespace depNamespace, Hook callback) Overloading of sendSubObjectResponse that takes a single dependent Namespace
protected void	setMessageHandler(MessageCallback handler)
protected void	setName(String name) Sets the name of the plugin.
static List<Serializable>	setObjectProperties(Long oid, Namespace namespace, Map<String,Serializable> propMap) EnginePlugin entrypoint which sets the object properties identified by the key/value pair in the propMap argument.
static List<Serializable>	setObjectProperties(Long oid, Namespace namespace, Serializable... keysAndValues) EnginePlugin entrypoint which sets the object properties identified by the alternating key and value arguments supplied as varargs.
static void	setObjectPropertiesNoResponse(Long oid, Namespace namespace, Map<String,Serializable> propMap) EnginePlugin entrypoint which sets the object properties identified by the key/value pair in the propMap argument.
static void	setObjectPropertiesNoResponse(Long oid, Namespace namespace, Serializable... keysAndValues) EnginePlugin entrypoint which sets the object properties identified by the alternating key and value arguments supplied as varargs.
static Serializable	setObjectProperty(Long oid, Namespace namespace, String key, Serializable value) EnginePlugin entrypoint which sets the object property identified by the key/value pair.
static void	setObjectPropertyNoResponse(Long oid, Namespace namespace, String key, Serializable value) EnginePlugin entrypoint which sets the object property identified by the key/value pair.
void	setPercentCPULoad(int percentCPULoad) Setter for percentCPULoad int.
void	setPluginAvailable(boolean avail)
void	setPluginInfo(String pluginInfo) Setter for pluginInfo string.
void	setPluginType(String pluginType) Setter for pluginType.
protected boolean	setPropertyImpl(EnginePlugin.SetPropertyMessage msg) Process the SetPropertyMessage, looking up the entity by oid and namespace, and setting the properties identified by the list of keys in the message.
boolean	transferObject(HashMap<String,Serializable> propMap, Entity entity) Transfers this object from this instance of this plugin, to another instance of this plugin.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

activateHookList

private LinkedList<EnginePlugin.PluginActivateHook> activateHookList

pluginState

String pluginState

THIS plugin's state

pluginStateMap

private Map<String,String> pluginStateMap

localNamespaces

Collection<Namespace> localNamespaces

A collection of Namespace objects associated with the plugin, initialized by the call to EnginePlugin.registerPluginNamespaces().

See Also:

#registerPluginNamespaces(Namespace, GenerateSubObjectHook)

engPluginMeter

MVMeter engPluginMeter

subObjectDepReadySub

private Long subObjectDepReadySub

Subscription for the object manager plugin SubObjectDepsReady message.

depLock

private Lock depLock

A lock serializing access to depsOutstanding collection.

depsOutstanding

Map<Long,Map<Namespace,Hook>> depsOutstanding

Add the list of namespaces paired with the hook to call to the list of outstanding dependencies for the oid. The caller of the hook will remove elements from the namespace list for the oid.

messageHandler

private MessageCallback messageHandler

hookManager

private HookManager hookManager

loadHookMap

private Map<Namespace,EnginePlugin.LoadHook> loadHookMap

unloadHookMap

private Map<Namespace,EnginePlugin.UnloadHook> unloadHookMap

deleteHookMap

private Map<Namespace,EnginePlugin.DeleteHook> deleteHookMap

name

private String name

pluginType

private String pluginType

pluginInfo

private String pluginInfo

percentCPULoad

private int percentCPULoad

pluginAvailable

private boolean pluginAvailable

lock

protected Lock lock

objLockManager

private ObjectLockManager objLockManager

MSG_TYPE_PLUGIN_STATE

public static MessageType MSG_TYPE_PLUGIN_STATE

MSG_TYPE_GET_PROPERTY

public static MessageType MSG_TYPE_GET_PROPERTY

MSG_TYPE_SET_PROPERTY

public static MessageType MSG_TYPE_SET_PROPERTY

MSG_TYPE_SET_PROPERTY_NONBLOCK

public static MessageType MSG_TYPE_SET_PROPERTY_NONBLOCK

dumpAllThreadSubscriptionLock

protected static Lock dumpAllThreadSubscriptionLock

dumpAllThreadSubscription

protected static Long dumpAllThreadSubscription

pluginStateSubscription

protected static Long pluginStateSubscription

subObjectSubscription

protected static Long subObjectSubscription

selectionSubscription

protected static Long selectionSubscription

selectionFilter

protected static INamespaceFilter selectionFilter

saveSubObjectSubscription

protected static Long saveSubObjectSubscription

loadSubObjectSubscription

protected static Long loadSubObjectSubscription

unloadSubObjectSubscription

protected static Long unloadSubObjectSubscription

deleteSubObjectSubscription

protected static Long deleteSubObjectSubscription

setSubObjectPersistenceSubscription

protected static Long setSubObjectPersistenceSubscription

propertySubscription

protected static Long propertySubscription

MSG_TYPE_DUMP_ALL_THREAD_STACKS

public static MessageType MSG_TYPE_DUMP_ALL_THREAD_STACKS

Message from proxy server, telling all processes to dump their thread stacks to the log.

MSG_TYPE_TRANSFER_OBJECT

public static final MessageType MSG_TYPE_TRANSFER_OBJECT

Message requesting transfer of an entity to a different world manager.

Constructor Detail

EnginePlugin

public EnginePlugin()

No args constructor (deprecated).

EnginePlugin

public EnginePlugin(String name)

constructor.

Parameters:

name - Plugin name, must be unique.

EnginePlugin

public EnginePlugin(String name,
                    EnginePlugin.PluginActivateHook activateHook)

constructor.

Parameters:

name - Plugin name which is used in broadcasting plugin availability and also used to find the plugin with Engine.getPlugin(String)

activateHook - called by the Engine when the plugin starts up

Method Detail

getName

public String getName()

Returns the name of the plugin. Engine.registerPlugin() will call this method and associate the name with the plugin, which can be retrieved by calling Engine.getPlugin()

Returns:

the name of this plugin

See Also:

setName(String)

setName

protected void setName(String name)

Sets the name of the plugin. The name is also used when the plugin is activated.

Parameters:

name - plugin name, must be unique

See Also:

getName()

setPluginType

public void setPluginType(String pluginType)

Setter for pluginType.

Parameters:

pluginType - The string type of the plugin.

getPluginType

public String getPluginType()

Getter for pluginType.

Returns:

The string type of the plugin

getStatusMap

public Map<String,String> getStatusMap()

Override to provide plugin status.

Specified by:

getStatusMap in interface StatusMapCallback

getPluginStatus

public String getPluginStatus()

Return the status string for the plugin

Returns:

A string of name=value pairs, comma separated, or the empty string

setPluginInfo

public void setPluginInfo(String pluginInfo)

Setter for pluginInfo string.

Parameters:

pluginInfo - The new string pluginInfo of the plugin.

getPluginInfo

public String getPluginInfo()

Getter for pluginInfo.

Returns:

The string pluginInfo of the plugin

setPercentCPULoad

public void setPercentCPULoad(int percentCPULoad)

Setter for percentCPULoad int.

Parameters:

percentCPULoad - The int percentCPULoad of the plugin.

getPercentCPULoad

public int getPercentCPULoad()

Getter for percentCPULoad.

Returns:

The int percentCPULoad of the plugin

registerActivateHook

public void registerActivateHook(EnginePlugin.PluginActivateHook hook)

Called on startup to initialize the plugin. You will typically extend this method to create subscriptions, and send out messages to other plugins. You should extend this to do your own logic if needed, no need to call super.onActivate()

Plugins are typically registered in config scripts calling Engine.registerPlugin(String classFile).

activate

public void activate()

called by the engine to initialize the plugin. you should not override this method since it sends out messages such as the PluginStatusMessage. this method calls onActivate() which you can override to implement your logic, therefore no need to call super.activate() you can alternately use registerActivateHook() if you are not extending the EnginePlugin class.

getPluginAvailable

public boolean getPluginAvailable()

setPluginAvailable

public void setPluginAvailable(boolean avail)

onActivate

public void onActivate()

for developers extending the EnginePlugin object, it may be easier to use the onActivate() method which gets called when the plugin is being activated by the Engine. this is an alternative to calling registerActivateHook()

getPluginState

public String getPluginState(String pluginName)

See EnginePlugin.PluginStateMessage.BuiltInState for some possible values

Parameters:

pluginName -

Returns:

pluginStateMap; null if state is unknown or not available

setMessageHandler

protected void setMessageHandler(MessageCallback handler)

getMessageHandler

protected MessageCallback getMessageHandler()

createSubscription

public void createSubscription(Hook hook,
                               MessageType msgType,
                               int flags)

helper method to create a subscription based on a message type and associate it with a hook for processing.

Parameters:

hook - hook processes any incoming messages

msgType - the message type to match. see Message.setMsgType()

handleMessage

public void handleMessage(Message msg,
                          int flags)

Callback method for subscriptions which by default calls hooks registered with this plugin's hookmanager via EnginePlugin.getHookManager(). Typically, you won't need to extend/replace this method unless you want to process messages in some way other than using the HookManager.

Specified by:

handleMessage in interface MessageCallback

Parameters:

msg - Message sent from other agent.

flags - Bitwise OR of MessageCallback.NO_FLAGS, MessageCallback.RESPONSE_EXPECTED.

See Also:

HookManager

handleMessageImpl

protected void handleMessageImpl(Message msg,
                                 int flags)

Iterate through the Hooks associated with the message type, calling each one's processMessage() method until one of them returns false.

Parameters:

msg - The message to be handled

flags - The flags associated with the message.

getPluginNamespaces

public Collection<Namespace> getPluginNamespaces()

Returns:

a copy of the collection of Namespace objects associated with the plugin.

See Also:

registerPluginNamespaces(java.util.Collection, multiverse.server.engine.EnginePlugin.GenerateSubObjectHook)

registerPluginNamespace

public void registerPluginNamespace(Namespace namespace,
                                    EnginePlugin.GenerateSubObjectHook genSubObjHook)

Register the plugin namespace, used to identify the kind of subobject created by this plugin.

Parameters:

namespace - The namespace object associated with the plugin

genSubObjHook - Called when sub-object is created in this plugin's namespace. Triggered by a generate sub-object message from the object manager.

registerPluginNamespaces

public void registerPluginNamespaces(Collection<Namespace> namespaces,
                                     EnginePlugin.GenerateSubObjectHook genSubObjHook)

Register plugin namespaces, used to identify the kind of subobject created by this plugin.

Parameters:

namespaces - The namespaces associated with the plugin

genSubObjHook - Called when sub-object is created in this plugin's namespace. Triggered by a generate sub-object message from the object manager.

registerPluginNamespaces

public void registerPluginNamespaces(Collection<Namespace> namespaces,
                                     EnginePlugin.GenerateSubObjectHook genSubObjHook,
                                     INamespaceFilter selectionFilter,
                                     INamespaceFilter subObjectFilter)

Register plugin namespaces, used to identify the kind of subobject created by this plugin.

Parameters:

namespaces - The namespaces associated with the plugin

genSubObjHook - Called when sub-object is created in this plugin's namespace. Triggered by a generate sub-object message from the object manager.

selectionFilter - A namespace filter for sub-object generation and loading. This filter should match sub-objects this plugin should own. The filter can be as simple as matching namespace (one plugin owns all the sub-objects), or more sophisticated. For example matching odd or even numbered OIDs (sub-objects split between two plugin instances), or matching locations (sub-objects split by geometry).

subObjectFilter - namespace filter for sub-object manipulation messages. This filter should match sub-objects loaded or generated into this plugin.

registerPluginNamespaces

public void registerPluginNamespaces(Collection<Namespace> namespaces,
                                     EnginePlugin.GenerateSubObjectHook genSubObjHook,
                                     Hook loadSubObjHook,
                                     Hook saveSubObjHook,
                                     Hook unloadSubObjHook,
                                     Hook deleteSubObjHook,
                                     INamespaceFilter selectionFilter,
                                     INamespaceFilter subObjectFilter)

Register namespaces this plugin is authoritative for. This method will create a subscription for GenerateSubObjectMessage, and add the passed in hook to process these messages. You should not create a second subscription. This method also creates a subscription for message type ObjectManagerClient.MSG_TYPE_SUB_OBJECT_DEPS_READY which the object manager sends when object creation dependencies are resolved. This method registers an internal hook to process dependency messages.

Parameters:

namespaces - Plugin's namespaces.

genSubObjHook - Called when sub-object is created in this plugin's namespace. Triggered by a generate sub-object message from the object manager.

loadSubObjHook - Override load sub obj hook, 'null' to use default hook.

saveSubObjHook - Override save sub obj hook, 'null' to use default hook.

unloadSubObjHook - Override unload sub obj hook, 'null' to use default hook.

deleteSubObjHook - Override delete sub obj hook, 'null' to use default hook.

selectionFilter - A namespace filter for sub-object generation and loading. This filter should match sub-objects this plugin should own. The filter can be as simple as matching namespace (one plugin owns all the sub-objects), or more sophisticated. For example matching odd or even numbered OIDs (sub-objects split between two plugin instances), or matching locations (sub-objects split by geometry).

subObjectFilter - namespace filter for sub-object manipulation messages. This filter should match sub-objects loaded or generated into this plugin.

registerSaveHook

public void registerSaveHook(Namespace namespace,
                             EnginePlugin.SaveHook saveHook)

Register a hook to be called when one of this plugin's sub object instances is saved.

Parameters:

namespace - The namespace in which this plugin's sub object instances reside.

saveHook - the hook to be used when your sub object is marked dirty and needs to be saved. it should handle deep copy if needed. this will be called by the persistenceManager when it wants to save the object. if saveHook is null, it will use the default handler which does not do a deep copy

registerLoadHook

public void registerLoadHook(Namespace namespace,
                             EnginePlugin.LoadHook loadHook)

Register a hook to be called when one of this plugin's sub object instances is loaded.

Parameters:

namespace - The namespace in which this plugin's sub object instances reside.

loadHook - The hook to be called when the sub object is loaded.

registerUnloadHook

public void registerUnloadHook(Namespace namespace,
                               EnginePlugin.UnloadHook unloadHook)

Register a hook to be called when one of this plugin's sub object instances is unloaded.

Parameters:

namespace - The namespace in which this plugin's sub object instances reside.

unloadHook - The hook to be called when the sub object is unloaded.

registerDeleteHook

public void registerDeleteHook(Namespace namespace,
                               EnginePlugin.DeleteHook deleteHook)

Register a hook to be called when one of this plugin's sub object instances is deleted.

Parameters:

namespace - The namespace in which this plugin's sub object instances reside.

deleteHook - The hook to be called when the sub object is deleted.

registerTransferHook

public void registerTransferHook(Filter filter,
                                 Hook hook)

Creates a subscription for transfer messages. Transfer messages get sent when an object switches ownership from one plugin to another instance of that plugin usually due to load balancing.

transferObject

public boolean transferObject(HashMap<String,Serializable> propMap,
                              Entity entity)

Transfers this object from this instance of this plugin, to another instance of this plugin. This is done by sending out a transfer message, which the other plugin is listening for when it called registerTransferHook(), probably in its onActivate() method. The caller is responsible for releasing any resources associated with the object. This call blocks until it gets a response message.

Parameters:

propMap - - we pass in HashMap because its serializable unlike Map

entity -

Returns:

success value

getHookManager

public HookManager getHookManager()

Returns the HookManager associated with this plugin. The HookManager's job is to match incoming subscription message with a hook that handles the message. Hooks are matched by calling msg.getMsgType() and comparing it with the hook's registered message type.

Returns:

HookManager associated with this plugin.

getObjectLockManager

protected ObjectLockManager getObjectLockManager()

Returns the ObjectLockManager associated with this plugin. Plugins do NOT share ObjectLockManagers, therefore locking one does not affect the other.

addToDepsOutstanding

private void addToDepsOutstanding(Long oid,
                                  Namespace namespace,
                                  Hook callback)

Associates the oid/namespace pair with the callbacks in the depsOutstanding map.

removeFromDepsOutstanding

private Hook removeFromDepsOutstanding(Long oid,
                                       Namespace namespace)

Removes the oid/namespace pair from the depsOutstanding map.

sendSubObjectResponse

public void sendSubObjectResponse(Message origMsg,
                                  Long oid,
                                  Namespace oidNamespace)

Overloading of sendSubObjectResponse used when there are no dependent Namespaces

Parameters:

origMsg - the original message to which we are responding

oid - oid of the sub object that was created

oidNamespace - the Namespace in which the new subobject should be created

sendSubObjectResponse

public void sendSubObjectResponse(Message origMsg,
                                  Long oid,
                                  Namespace oidNamespace,
                                  Namespace depNamespace,
                                  Hook callback)

Overloading of sendSubObjectResponse that takes a single dependent Namespace

Parameters:

origMsg - the original message to which we are responding

oid - oid of the sub object that was created

oidNamespace - the Namespace in which the new subobject should be created

depNamespace - the dependent Namespace object

callback - the callback when we dependencies are all ready.k

sendSubObjectResponse

public void sendSubObjectResponse(Message msg,
                                  Long oid,
                                  Namespace oidNamespace,
                                  LinkedList<Namespace> depNamespaces,
                                  Hook callback)

The plugin calls this after generating a sub object to let the object manager know the sub object is ready. In the case that the plugin needs other namespace data before creating the sub object, you can pass in a list of dependent namespaces, and the object manager plugin will send a notification message when all dependent sub objects have been created. Also sets the newly created entity's namespace

Parameters:

msg - the original message to which we are responding

oid - oid of the sub object that was created; the same as the master oid

oidNamespace - the Namespace in which the new subobject should be created

depNamespaces - collection of dependent Namespace objects

callback - the callback when we dependencies are all ready.

logDepsOutstanding

protected void logDepsOutstanding(String prefix,
                                  Long oid,
                                  Namespace ns)

A utility method to log depsOutstanding for the given oid

getPropertyImpl

protected boolean getPropertyImpl(EnginePlugin.GetPropertyMessage msg)

Process the GetPropertyMessage, looking up the entity by oid and namespace, and getting the properties identified by the list of keys in the message. Plugins can choose to override the default implementation of getPropertyImpl.

Parameters:

msg - The GetPropertyMessage instance.

Returns:

True if the entity could be found; false otherwise.

setPropertyImpl

protected boolean setPropertyImpl(EnginePlugin.SetPropertyMessage msg)

Process the SetPropertyMessage, looking up the entity by oid and namespace, and setting the properties identified by the list of keys in the message. In addition, sends a PropertyMessage with the keys and values gotten from the SetPropertyMessage. Plugins can choose to override the default implementation of setPropertyImpl.

Parameters:

msg - The SetPropertyMessage instance.

Returns:

True if the entity could be found; false otherwise.

getObjectProperty

public static Serializable getObjectProperty(Long oid,
                                             Namespace namespace,
                                             String key)

EnginePlugin entrypoint which gets the value of the object property associated with the given key

Parameters:

oid - The oid of the object

namespace - The namespace containing the object

key - The String key

Returns:

The value associated with the key, or null if none exists.

getObjectProperties

public static List<Serializable> getObjectProperties(Long oid,
                                                     Namespace namespace,
                                                     List<String> keys)

EnginePlugin entrypoint which gets a list of the values of the object properties associated with the given list of keys

Parameters:

oid - The oid of the object

namespace - The namespace containing the object

keys - A list of keys

Returns:

A list of values corresponding to those keys

getObjectProperties

public static List<Serializable> getObjectProperties(Long oid,
                                                     Namespace namespace,
                                                     String... keys)

EnginePlugin entrypoint which gets a list of the values of the object properties associated with the list of keys supplied as varargs

Parameters:

oid - The oid of the object

namespace - The namespace containing the object

keys - A list of keys

Returns:

A list of values corresponding to those keys

setObjectProperty

public static Serializable setObjectProperty(Long oid,
                                             Namespace namespace,
                                             String key,
                                             Serializable value)

EnginePlugin entrypoint which sets the object property identified by the key/value pair. This entrypoint waits for a response.

Parameters:

oid - The oid of the object

namespace - The namespace containing the object

key - The String key

value - The Serializable value to which to set the object's key property

Returns:

The previous value associated with the key

setObjectPropertyNoResponse

public static void setObjectPropertyNoResponse(Long oid,
                                               Namespace namespace,
                                               String key,
                                               Serializable value)

EnginePlugin entrypoint which sets the object property identified by the key/value pair. This entrypoint does not wait for a response.

Parameters:

oid - The oid of the object

namespace - The namespace containing the object

key - The String key

value - The Serializable value to which to set the object's key property

setObjectProperties

public static List<Serializable> setObjectProperties(Long oid,
                                                     Namespace namespace,
                                                     Map<String,Serializable> propMap)

EnginePlugin entrypoint which sets the object properties identified by the key/value pair in the propMap argument. This entrypoint waits for a response.

Parameters:

oid - The oid of the object

namespace - The namespace containing the object

propMap - The map of keys and values

Returns:

A list of the previous values associated with the keys.

setObjectProperties

public static List<Serializable> setObjectProperties(Long oid,
                                                     Namespace namespace,
                                                     Serializable... keysAndValues)

EnginePlugin entrypoint which sets the object properties identified by the alternating key and value arguments supplied as varargs. This entrypoint waits for a response.

Parameters:

oid - The oid of the object

namespace - The namespace containing the object

keysAndValues - The varargs sequence of key and value arguments

Returns:

A list of the previous values associated with the keys.

setObjectPropertiesNoResponse

public static void setObjectPropertiesNoResponse(Long oid,
                                                 Namespace namespace,
                                                 Map<String,Serializable> propMap)

EnginePlugin entrypoint which sets the object properties identified by the key/value pair in the propMap argument. This entrypoint does not wait for a response.

Parameters:

oid - The oid of the object

namespace - The namespace containing the object

propMap - The map of keys and values

setObjectPropertiesNoResponse

public static void setObjectPropertiesNoResponse(Long oid,
                                                 Namespace namespace,
                                                 Serializable... keysAndValues)

EnginePlugin entrypoint which sets the object properties identified by the alternating key and value arguments supplied as varargs. This entrypoint does not wait for a response.

Parameters:

oid - The oid of the object

namespace - The namespace containing the object

keysAndValues - The varargs sequence of key and value arguments

processKeysAndValues

protected static Map<String,Serializable> processKeysAndValues(String what,
                                                               Serializable[] keysAndValues)

A utility function to turn an array of keys and values into a propMap.

createManagementObject

private void createManagementObject()

createMBeanInstance

protected Object createMBeanInstance()