emulib.runtime

Class ContextPool

java.lang.Object

emulib.runtime.ContextPool

public class ContextPool
extends Object

This class manages all plug-in contexts. Plug-ins should register their contexts manually. Other plug-ins that have permissions, can gather contexts by querying this pool. Context pool is not thread safe.

Constructor Summary

Constructors

Constructor and Description
ContextPool()

Method Summary

Modifier and Type	Method and Description
void	clearAll(String password) Clear the context instance.
static String	computeHash(Class<? extends Context> contextInterface) Compute emuStudio-specific hash of the context interface.
<T extends CompilerContext> T	getCompilerContext(long pluginID, Class<T> contextInterface) Get registered compiler context.
<T extends CompilerContext> T	getCompilerContext(long pluginID, Class<T> contextInterface, int index) Get registered compiler context (extended version).
<T extends Context> T	getContext(long pluginID, Class<T> contextInterface, int index) Get plug-in context.
<T extends CPUContext> T	getCPUContext(long pluginID, Class<T> contextInterface) Get registered CPU context.
<T extends CPUContext> T	getCPUContext(long pluginID, Class<T> contextInterface, int index) Get registered CPU context (extended version).
<T extends DeviceContext> T	getDeviceContext(long pluginID, Class<T> contextInterface) Get registered device context.
<T extends DeviceContext> T	getDeviceContext(long pluginID, Class<T> contextInterface, int index) Get registered device context (extended version).
<T extends MemoryContext> T	getMemoryContext(long pluginID, Class<T> contextInterface) Get registered memory context.
<T extends MemoryContext> T	getMemoryContext(long pluginID, Class<T> contextInterface, int index) Get registered memory context (extended version).
void	register(long pluginID, Context context, Class<? extends Context> contextInterface) This method registers plug-in's context interface.
boolean	setComputer(String password, PluginConnections computer) Set a computer, represented as plug-in connections, loaded by emuStudio.
static String	SHA1(String text) Compute SHA-1 hash string.
boolean	unregister(long pluginID, Class<? extends Context> contextInterface) Unregisters all contexts of given context interface.

Methods inherited from class java.lang.Object

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

Constructor Detail

ContextPool

public ContextPool()

Method Detail

register

public void register(long pluginID,
                     Context context,
                     Class<? extends Context> contextInterface)
              throws AlreadyRegisteredException,
                     InvalidContextException

This method registers plug-in's context interface. The registration is needed because of contexts centralization. Other plug-ins can get a context by querying the pool. Usually, emuStudio does the job during loading of the virtual computer. Requirements for the context are: - It is allowed to implement one and only one context - context interface must extend Context interface provided by emuLib - context interface must be annotated with @ContextType annotation

Parameters:

pluginID - owner plugin ID of the context contextsByOwner

context - The context object that the plug-in want to register

contextInterface - The interface that the context has to implement

Throws:

AlreadyRegisteredException - Raised when a plug-in tries to register context that is already registered.

InvalidContextException - Raised when a class does not implement given interface, or it is not annotated, or if the context interface does not fulfill context requirements.

unregister

public boolean unregister(long pluginID,
                          Class<? extends Context> contextInterface)
                   throws InvalidContextException

Unregisters all contexts of given context interface. It will do it only if the plug-in has the permission. The permission is approved if and only if the contexts are implemented inside the plug-in.

Parameters:

pluginID - plugin ID of the context owner

contextInterface - the context interface

Returns:

true if at least one context was unregistered successfully, false otherwise.

Throws:

InvalidContextException - Raised when context interface is not annotated, or if the context interface does not fulfill context requirements.

setComputer

public boolean setComputer(String password,
                           PluginConnections computer)
                    throws InvalidPasswordException

Set a computer, represented as plug-in connections, loaded by emuStudio. This method should be called only by the emuStudio.

Parameters:

password - emuStudio password

computer - virtual computer, loaded by emuStudio

Returns:

true if computer was set successfully; false otherwise.

Throws:

InvalidPasswordException - if the password was incorrect

clearAll

public void clearAll(String password)
              throws InvalidPasswordException

Clear the context instance.

Parameters:

password - emuStudio password

Throws:

InvalidPasswordException - if the password was incorrect

getContext

public <T extends Context> T getContext(long pluginID,
                                        Class<T> contextInterface,
                                        int index)
                                 throws InvalidContextException,
                                        ContextNotFoundException

Get plug-in context.

Type Parameters:

T - Specific context type

Parameters:

pluginID - ID of requesting plug-in

contextInterface - wanted context interface (implemented by the plug-in)

index - the index if more than one context are found. If -1 is provided, any matched context is used

Returns:

requested context, which plugin owner != pluginId

Throws:

InvalidContextException - if the context interface does not fulfil context requirements

ContextNotFoundException - if the context does not exist or the plug-in is not allowed to get it

getCPUContext

public <T extends CPUContext> T getCPUContext(long pluginID,
                                              Class<T> contextInterface)
                                       throws InvalidContextException,
                                              ContextNotFoundException

Get registered CPU context. If plug-in doesn't have the permission to access it, return null. The permission is approved, when the plug-in is connected to the CPU in the abstract schema. If the CPU has more than one context implementing required context interface, the first one is returned. To access other ones, use extended version of the method. This method call is equivalent to the call of getCPUContext(pluginID, contextInterface, -1);

Type Parameters:

T - Specific CPU context

Parameters:

pluginID - plug-in requesting the CPU context

contextInterface - Interface of the context

Returns:

CPUContext object if it is found and the plug-in has the permission to access it; null otherwise

Throws:

InvalidContextException - if the context interface does not fulfil context requirements

ContextNotFoundException - if the context does not exist or the plug-in is not allowed to get it

getCPUContext

public <T extends CPUContext> T getCPUContext(long pluginID,
                                              Class<T> contextInterface,
                                              int index)
                                       throws InvalidContextException,
                                              ContextNotFoundException

Get registered CPU context (extended version). If plug-in doesn't have the permission to access it, return null. The permission is approved, when the plug-in is connected to the CPU in the abstract schema. If the CPU has more than one context implementing required context interface, it returns context indexed by index parameter.

Type Parameters:

T - Specific CPU Context

Parameters:

pluginID - plug-in requesting the CPU context

contextInterface - Interface of the context

index - 0-based the order of the context if they are more than one. Does nothing if the index is out of the bounds. If index is -1, it uses any found context.

Returns:

CPUContext object if it is found and the plug-in has the permission; null otherwise

Throws:

InvalidContextException - if the context interface does not fulfil context requirements

ContextNotFoundException - if the context does not exist or the plug-in is not allowed to get it

getCompilerContext

public <T extends CompilerContext> T getCompilerContext(long pluginID,
                                                        Class<T> contextInterface)
                                                 throws InvalidContextException,
                                                        ContextNotFoundException

Get registered compiler context. If plug-in doesn't have the permission to access it, return null. The permission is approved, when the plug-in is connected to the compiler in the abstract schema. If the compiler has more than one context implementing required context interface, the first one is returned. To access other ones, use extended version of the method. This method call is equivalent to the call of getCompilerContext(pluginID, contextInterface, -1);

Type Parameters:

T - Specific compiler context

Parameters:

pluginID - plug-in requesting the compiler context

contextInterface - Interface of the context, if requesting plugin has permission to acccess it

Returns:

CompilerContext object if it is found and the plug-in has the permission to access it; null otherwise

Throws:

InvalidContextException - if the context interface does not fulfil context requirements

ContextNotFoundException - if the context does not exist or the plug-in is not allowed to get it

getCompilerContext

public <T extends CompilerContext> T getCompilerContext(long pluginID,
                                                        Class<T> contextInterface,
                                                        int index)
                                                 throws InvalidContextException,
                                                        ContextNotFoundException

Get registered compiler context (extended version). If plug-in doesn't have the permission to access it, return null. The permission is approved, when the plug-in is connected to the compiler in the abstract schema. If the compiler has more than one context implementing required context interface, it returns context indexed by index parameter.

Type Parameters:

T - Specific compiler context

Parameters:

pluginID - plug-in requesting the Compiler context

contextInterface - Interface of the context

index - the order of the context if they are more than one. Does nothing if the index is out of bounds. If the index is -1, it uses any found context.

Returns:

CompilerContext object if it is found and the plug-in has the permission to access it; null otherwise

Throws:

InvalidContextException - if the context interface does not fulfil context requirements

ContextNotFoundException - if the context does not exist or the plug-in is not allowed to get it

getMemoryContext

public <T extends MemoryContext> T getMemoryContext(long pluginID,
                                                    Class<T> contextInterface)
                                             throws InvalidContextException,
                                                    ContextNotFoundException

Get registered memory context. If plug-in doesn't have the permission to access it, return null. The permission is approved, when the plug-in is connected to the memory in the abstract schema. If the memory has more than one context implementing required context interface, the first one is returned. To access other ones, use extended version of the method. This method call is equivalent to the call of getMemoryContext(pluginID, contextInterface, -1);

Type Parameters:

T - Specific memory context

Parameters:

pluginID - plug-in requesting the memory context

contextInterface - Interface of the context

Returns:

MemoryContext object if it is found and the plug-in has the permission to access it; null otherwise

Throws:

InvalidContextException - if the context interface does not fulfil context requirements

ContextNotFoundException - if the context does not exist or the plug-in is not allowed to get it

getMemoryContext

public <T extends MemoryContext> T getMemoryContext(long pluginID,
                                                    Class<T> contextInterface,
                                                    int index)
                                             throws InvalidContextException,
                                                    ContextNotFoundException

Get registered memory context (extended version). If plug-in doesn't have the permission to access it, return null. The permission is approved, when the plug-in is connected to the memory in the abstract schema. If the memory has more than one context implementing required context interface, it returns context indexed by index parameter.

Type Parameters:

T - Specific memory context

Parameters:

pluginID - plug-in requesting the memory context

contextInterface - Interface of the context

index - the index of the context if they are more than one. Does nothing if the index is out of bounds. If the index is -1, it uses any found context.

Returns:

MemoryContext object if it is found and the plug-in has the permission to access it; null otherwise

Throws:

InvalidContextException - if the context interface does not fulfil context requirements

ContextNotFoundException - if the context does not exist or the plug-in is not allowed to get it

getDeviceContext

public <T extends DeviceContext> T getDeviceContext(long pluginID,
                                                    Class<T> contextInterface)
                                             throws InvalidContextException,
                                                    ContextNotFoundException

Get registered device context. If plug-in doesn't have the permission to access it, return null. The permission is approved, when the plug-in is connected to the device in the abstract schema. If the device has more than one context implementing required context interface, the first one is returned. To access other ones, use extended version of the method. This method call is equivalent to the call of getDeviceContext(pluginID, contextInterface, -1);

Type Parameters:

T - Specific device context

Parameters:

pluginID - plug-in requesting the device context

contextInterface - Interface of the context

Returns:

DeviceContext object if it is found and the plug-in has the permission to access it; null otherwise

Throws:

InvalidContextException - if the context interface does not fulfil context requirements

ContextNotFoundException - if the context does not exist or the plug-in is not allowed to get it

getDeviceContext

public <T extends DeviceContext> T getDeviceContext(long pluginID,
                                                    Class<T> contextInterface,
                                                    int index)
                                             throws InvalidContextException,
                                                    ContextNotFoundException

Get registered device context (extended version). If plug-in doesn't have the permission to access it, return null. The permission is approved, when the plug-in is connected to the device in the abstract schema. If the device has more than one context implementing required context interface, it returns context indexed by index parameter.

Type Parameters:

T - Specific device context

Parameters:

pluginID - plug-in requesting the device context

contextInterface - Interface of the context

index - index of the context implementation. Does nothing if the index is out of bounds. If the index is -1, it uses any found context.

Returns:

DeviceContext object if it is found and the plug-in has the permission to access it; null otherwise

Throws:

InvalidContextException - if the context interface does not fulfil context requirements

ContextNotFoundException - if the context does not exist or the plug-in is not allowed to get it

computeHash

public static String computeHash(Class<? extends Context> contextInterface)

Compute emuStudio-specific hash of the context interface. The name of the interface is not important, only method names and their signatures. The final processing uses SHA-1 method.

Parameters:

contextInterface - interface to compute hash of

Returns:

SHA-1 hash string of the interface

SHA1

public static String SHA1(String text)
                   throws NoSuchAlgorithmException,
                          UnsupportedEncodingException

Compute SHA-1 hash string. Letters in the hash string will be in upper-case.

Parameters:

text - Data to make hash from

Returns:

SHA-1 hash Hexadecimal string, null if there was some error

Throws:

NoSuchAlgorithmException - self-descriptive

UnsupportedEncodingException - self-descriptive