leafchat.core.api
Interface PluginContext


public interface PluginContext

Interface that a plugin can use to request system services.


Field Summary
static int ALLREQUESTS
          Use in place of request ID to unrequest regardless of ID
 
Method Summary
 boolean dispatchExternalMessage(java.lang.Class<? extends Msg> message, Msg m, boolean immediate)
          Dispatch a message that is controlled by a MessageOwner in another plugin.
 void dispatchMsgToTarget(Msg m, java.lang.Object target)
          Dispatch message to a specific target (useful for re-handling your own messages, basically just calls the right msg() method).
 MessageInfo getMessageInfo(java.lang.Class<? extends Msg> c)
          Obtains information about any available message type.
 Plugin getPlugin()
           
<C extends Singleton>
C
getSingle(java.lang.Class<C> singletonInterface)
          Returns singleton implementing the desired interface.
 java.lang.Object getSingleton(java.lang.Class<? extends Singleton> singletonInterface)
          Deprecated. Replaced by getSingle(Class)
 void log(java.lang.String s)
          Log something to the system log.
 void log(java.lang.String s, java.lang.Throwable t)
          Log something to the system log.
 void logDebug(java.lang.String s)
          Log something to the system log if debug is turned on for this plugin.
 void logDebug(java.lang.String s, java.lang.Throwable t)
          Log something to the system log if debug is turned on for this plugin.
<C extends FactoryObject>
C
newFactoryObject(java.lang.Class<C> objectInterface)
          Get a new instance of a factory-created object.
 java.lang.Object newInstance(java.lang.Class<? extends FactoryObject> objectInterface)
          Deprecated. Replaced by newFactoryObject(Class)
 void registerExtraMessageClass(java.lang.Class<? extends Msg> c)
          Registers an additional message class (apart from the base type).
 void registerFactory(java.lang.Class<? extends FactoryObject> objectInterface, Factory f)
          Register an object as the factory creating objects of a given interface (which should be in the .api package)
 void registerMessageOwner(MsgOwner mo)
          Registers a new message type provided by this plugin.
<C extends Singleton>
void
registerSingleton(java.lang.Class<C> singletonInterface, C s)
          Register an object as the singleton implementing a given interface (which should be in the .api package)
 int requestMessages(java.lang.Class<? extends Msg> message, java.lang.Object target)
          Requests messages of a particular type, with no filter and PRIORITY_NORMAL.
 int requestMessages(java.lang.Class<? extends Msg> message, java.lang.Object target, int priority)
          Requests messages of a particular type, with no filter.
 int requestMessages(java.lang.Class<? extends Msg> message, java.lang.Object target, MessageFilter mf)
          Requests messages of a particular type, with PRIORITY_NORMAL.
 int requestMessages(java.lang.Class<? extends Msg> message, java.lang.Object target, MessageFilter mf, int priority)
          Requests messages of a particular type.
 void unrequestMessages(java.lang.Class<? extends Msg> message, java.lang.Object target, int requestID)
          Cancels a request for messages.
 void yield(java.lang.Runnable r)
          Runs the given runnable after all other messages are processed and the event queue is idle.
 

Field Detail

ALLREQUESTS

static final int ALLREQUESTS
Use in place of request ID to unrequest regardless of ID

See Also:
Constant Field Values
Method Detail

registerMessageOwner

void registerMessageOwner(MsgOwner mo)
Registers a new message type provided by this plugin. The fully qualified name of mo.getMessageClass() becomes the message type identifier. The specified message class will automatically have its message information registered; you need to call registerExtraMessageClass(Class) for each subclass.

Parameters:
mo - Owner that will generate messages of this type

registerExtraMessageClass

void registerExtraMessageClass(java.lang.Class<? extends Msg> c)
Registers an additional message class (apart from the base type). This adds the message class's info to the global set.

Parameters:
c - Message subclass.

requestMessages

int requestMessages(java.lang.Class<? extends Msg> message,
                    java.lang.Object target,
                    MessageFilter mf,
                    int priority)
Requests messages of a particular type. You may call multiple times e.g. with different filters, even for the same MessageTarget.

Parameters:
message - Message class
target - Target that wants messages
mf - Filter for messages (may be null)
priority - Priority for message (MessageTarget.PRIORITY_xxx)
Returns:
ID of request, used in unrequest.

requestMessages

int requestMessages(java.lang.Class<? extends Msg> message,
                    java.lang.Object target,
                    int priority)
Requests messages of a particular type, with no filter.

Parameters:
message - Message class
target - Target that wants messages
priority - Priority for message (MessageTarget.PRIORITY_xxx)
Returns:
ID of request, used in unrequest.

requestMessages

int requestMessages(java.lang.Class<? extends Msg> message,
                    java.lang.Object target,
                    MessageFilter mf)
Requests messages of a particular type, with PRIORITY_NORMAL.

Parameters:
message - Message class
target - Target that wants messages
mf - Filter for messages
Returns:
ID of request, used in unrequest.

requestMessages

int requestMessages(java.lang.Class<? extends Msg> message,
                    java.lang.Object target)
Requests messages of a particular type, with no filter and PRIORITY_NORMAL.

Parameters:
message - Message class
target - Target that wants messages
Returns:
ID of request, used in unrequest.

unrequestMessages

void unrequestMessages(java.lang.Class<? extends Msg> message,
                       java.lang.Object target,
                       int requestID)
Cancels a request for messages.

The system will automatically unrequest all messages when your plugin closes, so there is normally no need to call this method. You call this method only if, during your plugin's lifespan, there are some messages that you only need temporarily.

Does nothing if the plugin did not request messages with that ID.

Parameters:
message - Message class (may be null for 'all')
target - Target that no longer wants messages
requestID - ID returned by original request (may be PluginContext.ALLREQUESTS)

dispatchExternalMessage

boolean dispatchExternalMessage(java.lang.Class<? extends Msg> message,
                                Msg m,
                                boolean immediate)
                                throws GeneralException
Dispatch a message that is controlled by a MessageOwner in another plugin.

Don't use this for your own messages; for those, use the MessageDispatch class to dispatch.

The MessageOwner may reject this message rather than permitting its dispatch; in that case, this call will return false.

Parameters:
message - Class of message
m - Message to dispatch
immediate - True if message should be sent to all targets immediately before this message returns; false if it should be queued for later sending after other messages have been handled
Returns:
True if message was dispatched, false if it was prohibited
Throws:
GeneralException - If the message is of invalid type or the MessageOwner cannot be found

registerSingleton

<C extends Singleton> void registerSingleton(java.lang.Class<C> singletonInterface,
                                             C s)
                       throws BugException
Register an object as the singleton implementing a given interface (which should be in the .api package)

Parameters:
singletonInterface - Interface
s - Object implementing said interface
Throws:
BugException - If object doesn't implement interface, there's already an implementor of that interface, etc.

getSingle

<C extends Singleton> C getSingle(java.lang.Class<C> singletonInterface)
Returns singleton implementing the desired interface.

Parameters:
singletonInterface - Interface
Returns:
Singleton implementing interface
Throws:
BugException - If singleton doesn't exist or is of wrong type, etc.

getSingleton

java.lang.Object getSingleton(java.lang.Class<? extends Singleton> singletonInterface)
Deprecated. Replaced by getSingle(Class)

Returns singleton implementing the desired interface.

Parameters:
singletonInterface - Interface
Returns:
Singleton implementing interface (it is always safe to cast this into the interface)
Throws:
BugException - If singleton doesn't exist or is of wrong type, etc.

registerFactory

void registerFactory(java.lang.Class<? extends FactoryObject> objectInterface,
                     Factory f)
                     throws BugException
Register an object as the factory creating objects of a given interface (which should be in the .api package)

Parameters:
objectInterface - Interface
f - Factory that can create objects of said interface
Throws:
BugException - If there's already a factory for that interface

newFactoryObject

<C extends FactoryObject> C newFactoryObject(java.lang.Class<C> objectInterface)
                                         throws GeneralException
Get a new instance of a factory-created object.

Parameters:
objectInterface - Desired interface
Returns:
New object implementing cInterface
Throws:
GeneralException - If there is a problem creating the object

newInstance

java.lang.Object newInstance(java.lang.Class<? extends FactoryObject> objectInterface)
                             throws GeneralException
Deprecated. Replaced by newFactoryObject(Class)

Get a new instance of a factory-created object.

Parameters:
objectInterface - Desired interface
Returns:
New object implementing cInterface
Throws:
GeneralException - If there is a problem creating the object

dispatchMsgToTarget

void dispatchMsgToTarget(Msg m,
                         java.lang.Object target)
                         throws GeneralException
Dispatch message to a specific target (useful for re-handling your own messages, basically just calls the right msg() method). Message will go only to that target. Dispatch occurs immediately, call returns only when dispatch completes.

Parameters:
m - Message
target - Target to receive it
Throws:
GeneralException - E.g. if target doesn't have an appropriate msg()

log

void log(java.lang.String s)
Log something to the system log. The plugin's name will automatically be prepended.

Parameters:
s - String to log

log

void log(java.lang.String s,
         java.lang.Throwable t)
Log something to the system log. The plugin's name will automatically be prepended.

Parameters:
s - String to log
t - Exception to log (null for none)

logDebug

void logDebug(java.lang.String s)
Log something to the system log if debug is turned on for this plugin. The plugin's name will automatically be prepended.

Parameters:
s - String to log

logDebug

void logDebug(java.lang.String s,
              java.lang.Throwable t)
Log something to the system log if debug is turned on for this plugin. The plugin's name will automatically be prepended.

Parameters:
s - String to log
t - Exception to log (null for none)

getPlugin

Plugin getPlugin()
Returns:
The Plugin that owns this context.

yield

void yield(java.lang.Runnable r)
Runs the given runnable after all other messages are processed and the event queue is idle. (Basically this is so you don't need to call SwingUtilities.invokeLater.)

Parameters:
r - Task to run

getMessageInfo

MessageInfo getMessageInfo(java.lang.Class<? extends Msg> c)
                           throws BugException
Obtains information about any available message type. (If you need a list of all message classes you can start with Msg.class and follow the tree.)

Parameters:
c - Class to request
Returns:
Information
Throws:
BugException - If the class isn't registered


Copyright © 2011 Samuel Marshall. All rights reserved.