org.licas.server

Class LocalServer

java.lang.Object

org.licas.server.LocalServer

public class LocalServer
extends java.lang.Object

API for invoking methods on the HttpServer or ESB. These are both admin key protected now and so direct access is more difficult.

Author:

Kieran Greer

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	LocalServer() Create a new instance of LocalServer

Method Summary

Modifier and Type	Method and Description
boolean	addRootNode(java.lang.String theRootNode, java.lang.String adminKey) Add a service uuid to the list of root nodes.
boolean	addService(java.lang.String thePassword, java.lang.String serviceName, java.lang.String serviceType, java.lang.Object theService) Add a new service to the ESB but do not start its thread.
boolean	addServiceMeta(java.lang.String thePassword, java.lang.String theAdminKey, ServiceMeta theServiceMeta) Add the metadata for the service.
boolean	allowAddService(java.lang.String adminKey, boolean allow) Set the allowAddService variable to allow services to be added.
java.util.HashMap<java.lang.String,Metrics>	allServiceMetrics(java.lang.String adminKey) Get a list of all available services' metrics.
boolean	canAccess(java.lang.String thePassword, java.lang.reflect.Method theMethod) Return true if the password allows the calling component to access this component.
boolean	canAccess(java.lang.String thePassword, java.lang.String methodName) Return true if the password allows the calling component to access this component.
boolean	cancelMessage(java.lang.String ticket, java.lang.String adminKey) Remove the message with the specified ticket number from the queue.
static boolean	checkAddress(java.lang.String host, int port) Return true if the ip address and port compares to the address the server is running on.
static java.lang.String	contactInfo() Get a server administrator contact address, email or something.
java.lang.Object	execute(MethodInfo methodInfo) Execute the specified method and return the result.
boolean	getAllowAddService(java.lang.String adminKey) Return true if the ESB allows adding services.
static LocalServer	getApi(java.lang.String serverPassword) Get the local server instance.
Link_NM	getFaultsTree(java.lang.String adminKey) Get the faults list tree, for display purposes.
FileObject	getJarForService(java.lang.String jarName) Load a jar file into a file object and return.
java.lang.String	getPassword(java.lang.String clientID, Contract clientContract) Get this service's password, depending on the calling component's contract description.
static org.licas_xml.abs.Element	getServerHandle() Return the server handle of the static http server.
boolean	getServerShutDown() Return a value indicating if the static http server should be shut down.
static java.lang.String	getServerURL() Return the http address of the static http server.
java.lang.Object	getService(java.lang.String serviceName, java.lang.String thePassword, java.lang.String adminKey) Return the service for the related service name.
org.licas_xml.abs.Element	getServiceMeta(java.lang.String theServiceID) Get the metadata for the service from the server repository.
ServiceMeta	getServiceMeta(java.lang.String theServiceID, java.lang.String theAdminKey) Get the service metadata from the server repository.
java.util.ArrayList<java.lang.String>	getServiceNames() Get a list of services running on the ESB.
java.util.ArrayList<java.lang.String>	getServiceNames(java.util.ArrayList<java.lang.String> thisServiceTypes) Return all child service names for a list of service types.
java.util.ArrayList<java.lang.String>	getServiceNames(java.util.ArrayList<java.lang.String> thisServiceTypes, boolean reciprocal) Return all child service names for a list of service types.
java.lang.String	getServiceType(java.lang.String serviceID) Get the service type for the specified service.
java.util.ArrayList<java.lang.String>	getServiceTypes() Get a list of all of the service types in the network.
java.util.ArrayList<java.lang.String>	getServiceTypes(java.lang.String category) Get a list of all of the service types in the network for a particular category.
ServiceWrapperDef	getServiceWrapper(java.lang.String serviceName, java.lang.String thePassword, java.lang.String adminKey) Return the service wrapper for the related service name.
boolean	hasESB(java.lang.String thePassword) Return true if an enterprise service bus is running on this server.
boolean	hasJarFactory(java.lang.String thePassword) Return true if this server is running a jar factory.
static boolean	hasServer() Return true if an HttpServer instance is created.
static boolean	isAdminKey(java.lang.String theAdminKey) Return true if the correct admin key.
boolean	isBlockedService(java.lang.String serviceID) Return true if the service is a blocked service.
static boolean	isLocalIPAddress(java.lang.String theIPAddress) Return true if the ip address represents a local server.
static boolean	isPassword(java.lang.String theServerPassword) Return true if the correct password.
static boolean	isRunning() Return true if an enterprise service bus is stored and running in this server.
boolean	isStoredService(java.lang.String serviceID) Return true if the service id entered relates to a stored service.
boolean	messageToBus(MessageInfo ro, java.lang.String adminKey) Add the next message to the message bus, to be returned in order for processing by a service.
void	notifyOfFault(FaultDetails fault, java.lang.String adminKey) This method should be called to notify the server about a problem or fault.
org.licas_xml.abs.Element	passwordsStateToXml(java.lang.String adminKey) Serialize the stored ESB passwords list and return as an XML-based description.
boolean	removeServiceMeta(java.lang.String theServiceID, java.lang.String theAdminKey) Remove the service metadata from the server repository.
boolean	serverHasService(java.lang.String serviceID) Return true if a service with the specified id is running on this server.
boolean	serverHasServiceType(java.lang.String serviceType) Return true if a service with the specified type is running on this server.
boolean	setESB(java.lang.String serviceName, java.lang.String serviceType, java.util.ArrayList<java.lang.String> jarFile, java.lang.String className, java.util.ArrayList<java.lang.Object> params) Creates a user-defined instance of ESB and set with the config values.
boolean	setESB(java.lang.String serviceName, java.lang.String serviceType, org.licas_xml.abs.Element adminXml) Creates a default instance of ESB and set with the config values.
protected static void	setPasswords(java.lang.String thePassword, java.lang.String theAdminKey) Set the password and admin key for accessing the server.
boolean	shutDown(java.lang.String theAdminKey) Shut down the server and stop the request thread.
void	startRequestThread(java.lang.String adminKey) Start the server request thread.

Methods inherited from class java.lang.Object

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

Constructor Detail

LocalServer

protected LocalServer()

Create a new instance of LocalServer

Method Detail

getApi

public static LocalServer getApi(java.lang.String serverPassword)

Get the local server instance.

Parameters:

serverPassword - the server password or admin key.

Returns:

the local server api instance, or null if there is an error.

setPasswords

protected static void setPasswords(java.lang.String thePassword,
                                   java.lang.String theAdminKey)

Set the password and admin key for accessing the server. Can be set only once.

Parameters:

thePassword - the password for accessing the server.

theAdminKey - the admin key for accessing the server.

hasServer

public static boolean hasServer()

Return true if an HttpServer instance is created.

Returns:

true if a server instance has been created, false otherwise.

isRunning

public static boolean isRunning()

Return true if an enterprise service bus is stored and running in this server.

Returns:

true if this server is running with all components.

contactInfo

public static java.lang.String contactInfo()

Get a server administrator contact address, email or something.

Returns:

a server contact address.

isLocalIPAddress

public static boolean isLocalIPAddress(java.lang.String theIPAddress)

Return true if the ip address represents a local server.

Parameters:

theIPAddress - the ip address to compare, 127.0.0.1, for example.

Returns:

true if a local ipAddress.

canAccess

public boolean canAccess(java.lang.String thePassword,
                         java.lang.String methodName)

Return true if the password allows the calling component to access this component.

Parameters:

thePassword - the password to use.

methodName - the method name that needs to be called.

Returns:

true if the entered password is the correct password or there is no password.

canAccess

public boolean canAccess(java.lang.String thePassword,
                         java.lang.reflect.Method theMethod)

Return true if the password allows the calling component to access this component.

Parameters:

thePassword - the password to use.

theMethod - the method that needs to be called.

Returns:

true if the entered password is the correct password or there is no password.

getPassword

public java.lang.String getPassword(java.lang.String clientID,
                                    Contract clientContract)
                             throws java.lang.Exception

Get this service's password, depending on the calling component's contract description. By default, a service is assigned a 'yes' contract, meaning that it is open and will always return its password to allow for method invocation. The other default option is a 'no' contract, meaning that there is no negotiation and the password must be known. This can also be changed by adding a different 'sla' contract for each service level in the service. You can therefore override this method to provide your own checks, using this as a guide.

Parameters:

clientID - the clientID of the calling component.

clientContract - the description of the calling component's contract proposal.

Returns:

this overridden method passes the call to the nested ESB object that also uses the same password set. The server by default will always or never return its password.

Throws:

java.lang.Exception - any error.

checkAddress

public static boolean checkAddress(java.lang.String host,
                                   int port)

Return true if the ip address and port compares to the address the server is running on.

Parameters:

host - the host address. Can include 'localhost' or '127.0.0.1'.

port - the port.

Returns:

true if the whole address agrees with the server address.

getServerURL

public static java.lang.String getServerURL()

Return the http address of the static http server.

Returns:

the server URL address, with ip and port, or null if the server is not running.

getServerHandle

public static org.licas_xml.abs.Element getServerHandle()

Return the server handle of the static http server.

Returns:

the server URI, same as calling Handle.getLocalServerURI().

setESB

public boolean setESB(java.lang.String serviceName,
                      java.lang.String serviceType,
                      org.licas_xml.abs.Element adminXml)

Creates a default instance of ESB and set with the config values. Note that the ESB can be added only once, at the start of the server initialisation.

Parameters:

serviceName - the service name.

serviceType - the service type.

adminXml - the admin info or description of this service.

Returns:

true if added OK, false otherwise.

setESB

public boolean setESB(java.lang.String serviceName,
                      java.lang.String serviceType,
                      java.util.ArrayList<java.lang.String> jarFile,
                      java.lang.String className,
                      java.util.ArrayList<java.lang.Object> params)

Creates a user-defined instance of ESB and set with the config values. Note that the ESB can be added only once, at the start of the server initialisation.

Parameters:

serviceName - the name of the service.

serviceType - the type of the service.

jarFile - the jar files for a remote loading. Values are jar paths of type String.

className - the name of the service class.

params - a list of initialisation parameters.

Returns:

true if added OK, false otherwise.

startRequestThread

public void startRequestThread(java.lang.String adminKey)
                        throws java.lang.Exception

Start the server request thread.

Parameters:

adminKey - the server admin key.

Throws:

java.lang.Exception - any error.

messageToBus

public boolean messageToBus(MessageInfo ro,
                            java.lang.String adminKey)

Add the next message to the message bus, to be returned in order for processing by a service.

Parameters:

ro - the message to add, as the whole request object, that then executes itself and returns the result.

adminKey - admin key to access the server.

Returns:

true if the request object is added, false otherwise.

cancelMessage

public boolean cancelMessage(java.lang.String ticket,
                             java.lang.String adminKey)

Remove the message with the specified ticket number from the queue.

Parameters:

ticket - unique ticket number, equivalent to a communication ID.

adminKey - the server admin key.

Returns:

true if cancelled, false otherwise.

execute

public java.lang.Object execute(MethodInfo methodInfo)
                         throws java.lang.Exception

Execute the specified method and return the result. This executes on the ESB directly. Note that you can execute on a single instance of a service type by setting the methodInfo.serviceURI to be something like Handle.createServiceHandle(serviceType).

Parameters:

methodInfo - the method call description with all of the required information.

Returns:

the reply, any object.

Throws:

ServiceException - for non-critical service related problems, such as if the method password is incorrect.

java.lang.Exception - any error.

isBlockedService

public boolean isBlockedService(java.lang.String serviceID)

Return true if the service is a blocked service.

Parameters:

serviceID - the service uuid.

Returns:

true if (temporarily) blocked from being accessed, false otherwise.

allowAddService

public boolean allowAddService(java.lang.String adminKey,
                               boolean allow)

Set the allowAddService variable to allow services to be added.

Parameters:

adminKey - the admin key for this service.

allow - true if reset to allow adding of services, false to reset to block of adding services.

Returns:

true if the variable is set (adminKey OK), false otherwise.

getAllowAddService

public boolean getAllowAddService(java.lang.String adminKey)

Return true if the ESB allows adding services.

Parameters:

adminKey - the admin key for the server.

Returns:

true if services can be added, false otherwise.

addRootNode

public boolean addRootNode(java.lang.String theRootNode,
                           java.lang.String adminKey)

Add a service uuid to the list of root nodes. Note that the service itself must have been added previously. This method is only to declare it a root node in some hierarchical organisation structure.

Parameters:

theRootNode - the uuid of the root service to add.

adminKey - the server admin key.

Returns:

true if the node is added or false otherwise.

getService

public java.lang.Object getService(java.lang.String serviceName,
                                   java.lang.String thePassword,
                                   java.lang.String adminKey)
                            throws ServiceException,
                                   java.lang.Exception

Return the service for the related service name. This method requires the service admin key as well, but then returns a direct reference. A direct reference to the service itself is returned, no matter what the object type is.

Parameters:

serviceName - the name of the service you want to retrieve.

thePassword - the password for the service you want to retrieve.

adminKey - the admin key for the service you want to retrieve.

Returns:

the service object if it exists or null if it does not.

Throws:

ServiceException - for service specific error.

java.lang.Exception - any other error.

addService

public boolean addService(java.lang.String thePassword,
                          java.lang.String serviceName,
                          java.lang.String serviceType,
                          java.lang.Object theService)
                   throws java.lang.Exception

Add a new service to the ESB but do not start its thread.

Parameters:

thePassword - the password to protect access to this component.

serviceName - the name of the service.

serviceType - the type of the service.

theService - the service.

Returns:

true if the service has been added, false otherwise.

Throws:

java.lang.Exception - any error.

addServiceMeta

public boolean addServiceMeta(java.lang.String thePassword,
                              java.lang.String theAdminKey,
                              ServiceMeta theServiceMeta)

Add the metadata for the service.

Parameters:

thePassword - the service password. Register if not already added.

theAdminKey - the admin key for the service. Register if not already added.

theServiceMeta - the metadata for the service.

Returns:

true if added OK, false otherwise.

getServiceMeta

public org.licas_xml.abs.Element getServiceMeta(java.lang.String theServiceID)
                                         throws java.lang.Exception

Get the metadata for the service from the server repository.

Parameters:

theServiceID - the unique id to define the service.

Returns:

the metadata in XML format if it exists or null if it does not.

Throws:

java.lang.Exception - any error.

getServiceMeta

public ServiceMeta getServiceMeta(java.lang.String theServiceID,
                                  java.lang.String theAdminKey)
                           throws java.lang.Exception

Get the service metadata from the server repository.

Parameters:

theServiceID - the unique id to define the service.

theAdminKey - the unique admin key for the service.

Returns:

a direct reference to the object itself so that it can be changed.

Throws:

java.lang.Exception - any error.

removeServiceMeta

public boolean removeServiceMeta(java.lang.String theServiceID,
                                 java.lang.String theAdminKey)
                          throws java.lang.Exception

Remove the service metadata from the server repository.

Parameters:

theServiceID - the unique id of the service to remove.

theAdminKey - the unique admin key for the service.

Returns:

true if the info is removed or false otherwise.

Throws:

java.lang.Exception - any error.

getServiceWrapper

public ServiceWrapperDef getServiceWrapper(java.lang.String serviceName,
                                           java.lang.String thePassword,
                                           java.lang.String adminKey)
                                    throws ServiceException,
                                           java.lang.Exception

Return the service wrapper for the related service name. This method requires the admin key as well, and then returns a direct reference to the wrapper only. Some methods may be executed on the wrapper and not the service.

Parameters:

serviceName - the name of the service you want to retrieve.

thePassword - the password to access the service you want to retrieve.

adminKey - the admin key for the service you want to retrieve.

Returns:

the service object if it exists or null if it does not.

Throws:

ServiceException - for service specific error.

java.lang.Exception - any other error.

getServiceNames

public java.util.ArrayList<java.lang.String> getServiceNames()

Get a list of services running on the ESB. This is public information.

Returns:

all service uuids, of type String.

getServiceNames

public java.util.ArrayList<java.lang.String> getServiceNames(java.util.ArrayList<java.lang.String> thisServiceTypes)
                                                      throws LicasException

Return all child service names for a list of service types.

Parameters:

thisServiceTypes - the service types list.

Returns:

the service names for the service types list.

Throws:

LicasException - if the service types input is null.

getServiceNames

public java.util.ArrayList<java.lang.String> getServiceNames(java.util.ArrayList<java.lang.String> thisServiceTypes,
                                                             boolean reciprocal)
                                                      throws LicasException

Return all child service names for a list of service types.

Parameters:

thisServiceTypes - the service types list.

reciprocal - is false return all service names of the service types, if true return all service names of all other types.

Returns:

the service names for the service types list.

Throws:

LicasException - if the service types input is null.

getServiceType

public java.lang.String getServiceType(java.lang.String serviceID)

Get the service type for the specified service.

Parameters:

serviceID - id of the service to retrieve.

Returns:

a list of all of the service types, of type String.

getServiceTypes

public java.util.ArrayList<java.lang.String> getServiceTypes()

Get a list of all of the service types in the network.

Returns:

a list of all of the service types, of type String.

getServiceTypes

public java.util.ArrayList<java.lang.String> getServiceTypes(java.lang.String category)

Get a list of all of the service types in the network for a particular category.

Parameters:

category - the category to return service types for.

Returns:

a list of all of the service types, of type String.

passwordsStateToXml

public org.licas_xml.abs.Element passwordsStateToXml(java.lang.String adminKey)

Serialize the stored ESB passwords list and return as an XML-based description.

Parameters:

adminKey - the ESB admin key.

Returns:

an XML representation of all passwords, or null if the admin key is incorrect.

allServiceMetrics

public java.util.HashMap<java.lang.String,Metrics> allServiceMetrics(java.lang.String adminKey)

Get a list of all available services' metrics.

Parameters:

adminKey - the admin key for the server.

Returns:

the service metric stats, key is the service id.

notifyOfFault

public void notifyOfFault(FaultDetails fault,
                          java.lang.String adminKey)

This method should be called to notify the server about a problem or fault. It could also happen automatically through the autonomic manager, for example, but extra coding is required for that. The fault details are read and stored in a tree structure for analysis. Only minimal additional action is taken, such as removing or blocking the offending entity. See the documentation for more details.

Parameters:

fault - a description of the fault.

adminKey - server admin key. If this is incorrect, then the fault is not recorded.

getFaultsTree

public Link_NM getFaultsTree(java.lang.String adminKey)

Get the faults list tree, for display purposes.

Parameters:

adminKey - the admin key for the server.

Returns:

the value of faults.

isPassword

public static boolean isPassword(java.lang.String theServerPassword)

Return true if the correct password.

Parameters:

theServerPassword - the password to check for.

Returns:

true if the correct password.

isAdminKey

public static boolean isAdminKey(java.lang.String theAdminKey)

Return true if the correct admin key.

Parameters:

theAdminKey - the admin key to check for.

Returns:

true if the correct admin key.

hasESB

public boolean hasESB(java.lang.String thePassword)

Return true if an enterprise service bus is running on this server.

Parameters:

thePassword - the password for this server.

Returns:

true if an ESB has already been loaded.

hasJarFactory

public boolean hasJarFactory(java.lang.String thePassword)

Return true if this server is running a jar factory.

Parameters:

thePassword - the password for this server.

Returns:

true if a jar factory is installed.

serverHasService

public boolean serverHasService(java.lang.String serviceID)
                         throws java.lang.Exception

Return true if a service with the specified id is running on this server.

Parameters:

serviceID - the service uuid to check for.

Returns:

true if a service with that ID is running, false otherwise.

Throws:

java.lang.Exception - any error.

serverHasServiceType

public boolean serverHasServiceType(java.lang.String serviceType)

Return true if a service with the specified type is running on this server.

Parameters:

serviceType - the service type to check for.

Returns:

true if a service of that type is running, false otherwise.

isStoredService

public boolean isStoredService(java.lang.String serviceID)

Return true if the service id entered relates to a stored service. This relates to metadata stored in the repository and so it might be a utility service or a base service, so it is slightly different to the serverHasService method.

Parameters:

serviceID - the unique service id.

Returns:

true if the related service is stored on this server.

getJarForService

public FileObject getJarForService(java.lang.String jarName)

Load a jar file into a file object and return. The jar file must be stored in the default services folder location. It must also be compiled into a single package as no third party jar files will be loaded as well.

Parameters:

jarName - the name of the jar file.

Returns:

the created file object.

getServerShutDown

public boolean getServerShutDown()

Return a value indicating if the static http server should be shut down.

Returns:

a value if the server should be shut down.

shutDown

public boolean shutDown(java.lang.String theAdminKey)

Shut down the server and stop the request thread.

Parameters:

theAdminKey - the unique key to protect loading/removal of the server.

Returns:

true if shut down OK.