org.licas.server

Class ESB

java.lang.Object

java.lang.Thread

org.licas.module.LicasModule

org.licas.module.FrameworkModule

org.licas.module.ServiceModule

org.licas.Service

org.licas.service.DataService

org.licas.Auto

org.licas.AutoSecure

org.licas.server.ESB

All Implemented Interfaces:

java.lang.AutoCloseable, java.lang.Runnable, BusDef, DataServiceDef, PublishSubscribeDef, ServiceDef

public class ESB
extends AutoSecure
implements BusDef, PublishSubscribeDef

This is a base class that acts as a lightweight server manager for the loaded services. This is based on an Enterprise Service Bus, to put it in the context of an SOA architecture. It is derived from a Service class and so uses all of those methods. In addition, it has new methods for searching over service metadata and managing the method invocation calls.

This is stored as a service on an HttpServer and anything loaded onto the licas server actually gets stored here. This class therefore controls service creation and making method invocations on them. This class also stores the metadata descriptions in a ServerMetadata repository. Remote communications are sent to the HttpServer class through an HTTP protocol that then passes these onto this class for processing. The HttpServer however still has some methods that can be queried for server-only requests.

Any service that is loaded and registered here is a base service. All services are contained in a wrapper first, where any Auto-derived service loaded here is contained by an AutonomicManager wrapper. Any non Auto-derived service or any service loaded to some other component does not have an Autonomic Manager, but is wrapped by a ServiceWrapper instead. As well as the functionality, these extra wrappers provide some levels of security.

Author:

Kieran Greer.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler

Field Summary

Fields

Modifier and Type	Field and Description
protected AutoMetaSearch	autoMetaSearch Stats search facility over the loaded services.
protected java.util.ArrayList<java.lang.String>	blockedServices A list of services that cannot be accessed because permission is blocked.
protected static java.lang.String	commFault Fault communication id
protected HttpServer	httpBase Base http server.
protected LicasDocSearch	licasDocSearch Text document search facility over the allowed folders.
protected MessageMediator	messageMediator This class mediates the process of passing messages between the server and the services.
protected PacketMessages	messagePackets Stores communication ids with related message packet info for receiving messages in packets.
protected Metrics	metrics Server metrics.
protected java.util.ArrayList<java.lang.String>	rootNodes The uuids of services that are root nodes in a hierarchical network.
protected ServerMetadata	serverMetadata Metadata repository for registered services.
protected ServerMetaSearch	serverMetaSearch Metadata search facility over the registered services, based on XML pattern matching.
protected java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>>	serverServices List of global services that can be called by any other service and are controlled by the server.
protected UtilsManagerDef	utilsManager Server utilities manager.

Fields inherited from class org.licas.Auto

autoEngine, autoManager, bm, iterations, sleepTime

Fields inherited from class org.licas.service.DataService

dataCompare, dataMethod, resultObj

Fields inherited from class org.licas.Service

canAccessMeta, canAccessNested, dm, finalised, isRemoteCall, messageStore, serviceAdmin, serviceGrade, serviceInitialise, serviceLinks, serviceState, sm, toLoadScript

Fields inherited from class org.licas.module.ServiceModule

shutDown

Fields inherited from class org.licas.module.FrameworkModule

passwordHandler, service, serviceType

Fields inherited from class org.licas.module.LicasModule

jarFile, syncOn, uuid

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Constructor and Description
ESB(java.lang.String password, java.lang.String thisAdminKey) Creates a new instance of ESB.
ESB(java.lang.String thisPassword, java.lang.String thisAdminKey, org.licas_xml.abs.Element adminXml) Creates a new instance of ESB.
ESB(java.lang.String thisPassword, java.lang.String thisAdminKey, org.licas_xml.abs.Element adminXml, java.lang.String resManClass) Creates a new instance of ESB.

Method Summary

Modifier and Type	Method and Description
boolean	addLoader(java.lang.String thePassword, java.util.ArrayList<java.lang.String> uris) Add a new class loader from remote uris.
protected void	addMessageMetrics(MethodInfo messageInfo, java.lang.String thePassword) Add metric or stat values for the message object.
boolean	addMessagePacket(java.lang.String communicationID, java.lang.String packetObject) Add the message packet to the appropriate file as indicated by the communication id.
boolean	addObject(java.lang.String thePassword, java.lang.String className, java.util.ArrayList<java.lang.String> uris) Create a new instance of an object, with no initialisation parameters.
boolean	addPacketCommunicationID(java.lang.String communicationID, int packetSize) Add the communication id and packet info to the packetInfo structure.
boolean	addParser(java.lang.String thePassword, java.lang.String objectClass, java.lang.String parserClass, java.util.ArrayList<java.lang.String> uris, java.util.ArrayList<java.lang.Object> params) Add a new parser to the parsers.
protected boolean	addRootNode(java.lang.String theRootNode, java.lang.String theAdminKey) Add a service uuid to the list of root nodes.
boolean	addServiceMeta(java.lang.String thePassword, java.lang.String theAdminKey, ServiceMeta theServiceMeta) Add the metadata for the service.
java.util.HashMap<java.lang.String,Metrics>	allServiceMetrics(java.lang.String adminKey) Get the stats for all services.
protected void	autoManFault(Link_NM message) Add the fault tree to the autonomic manager queue for processing.
protected MessageInfo	behaviourAction(MessageInfo messageInfo) Periodically run some server utility functions to monitor the system state.
boolean	blockService(java.lang.String serviceUuid, java.lang.String adminKey) Block the service from being accessed.
void	calculateRootNodes(java.lang.String theAdminKey) Calculate what nodes are root nodes, that is, are not children of any other nodes.
boolean	cancelMessage(java.lang.String ticket, java.lang.String adminKey) Remove the message with the specified ticket number from the queue.
void	clearNetwork(java.util.ArrayList<java.lang.String> serviceTypes, boolean keepRemove, java.lang.String adminKey) Remove all components of the network currently running on this server, but only of the specified service type.
void	clearNetwork(java.lang.String adminKey) Remove all components of the network currently running on this server.
void	close() Clean-up before shutting down the service.
protected ServiceWrapperDef	createServiceWrapper(java.lang.Object serviceObj, java.lang.String serviceName, java.lang.String serviceType, java.util.ArrayList<java.lang.String> jarFiles, org.licas_xml.abs.Element adminXml) Create a service wrapper for storing the service object.
java.lang.Object	endOfMessage(java.lang.String communicationID) Call this to indicate that the whole message has been sent and should now be executed.
org.licas_xml.abs.Element	executeServiceType(java.lang.String serviceType, MethodInfo methodInfo) Execute a synchronous method on a service type known by the server and probably owned locally.
void	executeServiceTypeAsync(java.lang.String serviceType, MethodInfo methodInfo) Execute an asynchronous method on the server, or a service type known by the server.
java.lang.String	getAdminKey(java.lang.String serviceID, java.lang.String thisAdminKey) Get the service key for the specified service.
org.licas_xml.abs.Element	getAllServiceMeta() Get a default subset of the metadata for the full service list, for info purposes only.
org.licas_xml.abs.Element	getAllServiceMeta(java.util.ArrayList<java.lang.String> serviceNames) Get a default subset of the metadata for the specified list of services, for info purposes only.
java.util.ArrayList<java.lang.String>	getRootNodes(java.lang.String theAdminKey) Get a copy list of the root nodes.
protected java.util.ArrayList<java.lang.String>	getSecureMethods() Get the list of methods that can be safely called on a secure server.
org.licas_xml.abs.Element	getServerDetails(java.lang.String theAdminKey) Retrieve a description of the server itself in XML format.
protected java.lang.String	getServerPassword() Get the local server password, which is the ESB password as well.
java.util.HashMap<java.lang.String,org.licas_xml.abs.Element>	getServerSOA(java.lang.String theAdminKey) Retrieve a description of the whole network structure in XML format.
org.licas_xml.abs.Element	getServiceMeta(java.lang.String theServiceID) Get a default subset of the metadata for the service, for info purposes only.
ServiceMeta	getServiceMeta(java.lang.String theServiceID, java.lang.String theAdminKey) Get the full service metadata description from the repository.
org.licas_xml.abs.Element	getServiceMeta(java.lang.String theServiceID, java.lang.String theAdminKey, java.util.ArrayList<java.lang.String> toInclude) Get a default subset of the metadata for the service, plus other sections.
org.licas_xml.abs.Element	getServiceMetaPart(java.lang.String theServiceID, java.lang.String theAdminKey, java.lang.String toInclude) Retrieve just one part of the metadata description, not the whole object.
protected java.util.ArrayList<java.lang.String>	getServiceNamesPermission() Return all registered service names.
protected java.util.ArrayList<java.lang.String>	getServiceTypeNamesPermission(java.util.ArrayList<java.lang.String> thisServiceTypes) Return all registered service names for a list of service types.
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.
protected ServiceWrapperDef	getServiceWrapper(java.lang.String serviceName, java.lang.String thePassword, java.lang.String adminKey) Return the service wrapper for the related service name.
org.licas_xml.abs.Element	getStats(java.lang.String queryType, java.lang.String adminKey) Get the query stats.
protected boolean	hasServerPassword() Return true if the local server password is stored.
protected boolean	isBlockedService(java.lang.String serviceID) Return true if the service is blocked from access.
boolean	isServer() Return true if this module is a base server module.
protected boolean	isStoredService(java.lang.String theServiceID) Return true if the service id is stored for a loaded service.
boolean	loadServerDetails(org.licas_xml.abs.Element serverXml, java.lang.String theAdminKey) Add the details as specified in the xml script to the server.
java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>>	loadServerSOA(java.util.HashMap<java.lang.String,org.licas_xml.abs.Element> networkXML, java.lang.String theAdminKey) Load the network described by the list of XML-based documents onto the server.
java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>>	loadServerSOA(java.lang.String dirPath, java.lang.String theAdminKey) Load the network described by the list of XML-based documents onto the server.
boolean	loadServiceFromXml(org.licas_xml.abs.Element serviceXml, java.lang.String theAdminKey) Create and load a serialized service from its XML description.
java.lang.Object	messageBus(MethodInfo methodInfo) Execute a call on the system message bus.
protected boolean	messageToBus(MessageInfo ro, java.lang.String adminKey) Add the message to the message bus queue for subsequent processing.
org.licas_xml.abs.Element	passwordsStateToXml(java.lang.String adminKey) Serialize the stored passwords list and return as an XML-based description.
boolean	publish(WorkInfo workInfo) Publish to provide information as an Information service.
boolean	removeAllLinksTo(java.lang.String theServiceID, java.lang.String theAdminKey) Remove all non-dynamic links to the specified service from all other services.
boolean	removeParser(java.lang.String thePassword, java.lang.String objectClass) Remove the parser from the parsers if it exists.
boolean	removeRootNode(java.lang.String theRootNode, java.lang.String theAdminKey) Remove a service uuid from the list of root nodes.
protected boolean	removeServiceMeta(java.lang.String theServiceID, java.lang.String theAdminKey) Remove the service metadata from the repository.
Metrics	serviceMetrics(java.lang.String serviceID, java.lang.String serverAdminKey) Get the stats for the specified service.
protected void	setServer(HttpServer thisHttpBase) Set the base http server.
boolean	subscribe(WorkInfo workInfo) Subscribe to receive information from an Information service.
boolean	unblockService(java.lang.String serviceUuid, java.lang.String adminKey) Unblock the service to re-allow access.
void	unpublish(KeywordInfo keyInfo, org.licas_xml.abs.Element serviceURI) Un-publish to provide information.
void	unsubscribe(KeywordInfo keyInfo, org.licas_xml.abs.Element clientURI) Un-subscribe from a service.

Methods inherited from class org.licas.AutoSecure

canAccess, classNameOK, getInstanceValue, getPublicMethods, isSecureMethod, setInstanceValues, setSerializeValues

Methods inherited from class org.licas.Auto

autoAction, autoQueueMessage, getAutoEngine, getMessageState, interrupt, invokeBehaviour, messageReply, removeCommunicationID, run, setAutoEngine, setAutonomicManager, setBehaviourModule, setProcessScript

Methods inherited from class org.licas.service.DataService

createEvaluateData, createEvaluateData, dataTypeOK, dataXmlBM, dataXmlBM, dataXmlDH, dataXmlDH, evaluate, getData, getData, getDataType, getResultObj, resetValues, setData, setData, setFixedDataValue, setGenData, setResultObj

Methods inherited from class org.licas.Service

addCommunicationID, addDefaultService, addDefaultService, addDefaultService, addDefaultService, addLinkFromService, addLinkToService, addService, addService, addService, addService, addServiceAssociation, addServicePassword, addTempPassword, allowAddService, canAccess, canAccess, canAccess, canAccessMeta, canAccessNested, canAccessTemp, canRun, clearServiceLinks, clearServices, clearServices, createMetaForRepos, createMetaFull, createPermanentLinkTo, defaultAdminToRemove, dynamicLinkQuery, dynamicLinksToPermanent, dynamicLinksToXml, dynamicLinksToXml, execute, finaliseInitialisation, finaliseInitialisation, finaliseModule, finaliseThisConfig, GET, getAllLinkToService, getAllowAddService, getAutonomicManagerConfig, getCommunicationClientURI, getDescription, getFullPath, getIsRemoteCall, getLinkFromService, getLinkToService, getLocalRemoteID, getParent, getParent, getPassword, getPassword, getPassword, getPasswordHandler, getPrivateMethods, getPublicServiceClassname, getService, getService, getServiceAdmin, getServiceClasses, getServiceGrade, getServiceLinks, getServiceNames, getServiceNames, getServiceNames, getServiceNumber, getServiceOrWrapper, getServiceState, getServiceType, handshake, hasCommunicationID, hasLinkTo, hasService, hasServiceType, isCorrectPassword, isPrivateMethod, isPublicMethod, isStarted, linksToXml, permanentLinksToXml, reflectionMethods, reflectionObject, removeAllServices, removeAllServices, removeLinkFromService, removeLinkToService, removePermanentLinkTo, removeServiceAssociation, removeServiceID, removeServicePath, removeServicePath, removeTempPassword, serviceNegotiate, serviceToXml, serviceToXml, setAdminInfo, setCanAccessMeta, setCanAccessNested, setData, setDataModule, setDataModule, setDescription, setIsRemoteCall, setOtherMeta, setParent, setParent, setServerPassword, setServiceGrade, setServiceModule, setServiceState, startAllThreads, startThread, stopAllThreads, syncToAsync, syncToAsyncReply, syncToAsyncTransit, xmlToDynamicLinks, xmlToService

Methods inherited from class org.licas.module.ServiceModule

getShutDown, setShutDown, setShutDown

Methods inherited from class org.licas.module.FrameworkModule

canAccess, getPasswordHandler, getServicePassword, getServiceType, isAdminKey, setServiceDetails, setServiceType

Methods inherited from class org.licas.module.LicasModule

getJarFile, getUUID, loadObject, setJarFile, setUUID, threadAliveState

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.licas.def.DataServiceDef

setData

Methods inherited from interface org.licas.def.ServiceDef

getUUID, setJarFile, setUUID

Field Detail

commFault

protected static java.lang.String commFault

Fault communication id

rootNodes

protected java.util.ArrayList<java.lang.String> rootNodes

The uuids of services that are root nodes in a hierarchical network.

serverServices

protected java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>> serverServices

List of global services that can be called by any other service and are controlled by the server. Key is the service type and value is a list of service UUIDs.

blockedServices

protected java.util.ArrayList<java.lang.String> blockedServices

A list of services that cannot be accessed because permission is blocked.

metrics

protected Metrics metrics

Server metrics.

messageMediator

protected MessageMediator messageMediator

This class mediates the process of passing messages between the server and the services.

utilsManager

protected UtilsManagerDef utilsManager

Server utilities manager.

serverMetadata

protected ServerMetadata serverMetadata

Metadata repository for registered services.

serverMetaSearch

protected ServerMetaSearch serverMetaSearch

Metadata search facility over the registered services, based on XML pattern matching.

licasDocSearch

protected LicasDocSearch licasDocSearch

Text document search facility over the allowed folders.

autoMetaSearch

protected AutoMetaSearch autoMetaSearch

Stats search facility over the loaded services. This is based on accumulated stats produced by the autonomic managers.

messagePackets

protected PacketMessages messagePackets

Stores communication ids with related message packet info for receiving messages in packets. Keys are the communication ids of type String, while values are the PacketInfo objects.

httpBase

protected HttpServer httpBase

Base http server.

Constructor Detail

ESB

public ESB(java.lang.String password,
           java.lang.String thisAdminKey)
    throws java.lang.Exception

Creates a new instance of ESB.

Parameters:

password - the password to access the server with.

thisAdminKey - a unique key to protect loading/removal.

Throws:

java.lang.Exception - any error.

ESB

public ESB(java.lang.String thisPassword,
           java.lang.String thisAdminKey,
           org.licas_xml.abs.Element adminXml)
    throws java.lang.Exception

Creates a new instance of ESB.

Parameters:

thisPassword - the component password.

thisAdminKey - the unique service key.

adminXml - the admin info or description of this service.

Throws:

java.lang.Exception - any error.

ESB

public ESB(java.lang.String thisPassword,
           java.lang.String thisAdminKey,
           org.licas_xml.abs.Element adminXml,
           java.lang.String resManClass)
    throws java.lang.Exception

Creates a new instance of ESB.

Parameters:

thisPassword - the component password.

thisAdminKey - the unique service key.

adminXml - the admin info or description of this service.

resManClass - the class type for the resource manager. No constructor parameters and jar file must be available.

Throws:

java.lang.Exception - any error.

Method Detail

isServer

public boolean isServer()

Return true if this module is a base server module.

Returns:

true in this case.

behaviourAction

protected MessageInfo behaviourAction(MessageInfo messageInfo)
                               throws java.lang.Exception

Periodically run some server utility functions to monitor the system state.

Specified by:

behaviourAction in class Auto

Parameters:

messageInfo - the message to evaluate.

Returns:

null in this case, as this is only a periodic monitoring check.

Throws:

java.lang.Exception - any error.

setServer

protected void setServer(HttpServer thisHttpBase)
                  throws java.lang.Exception

Set the base http server.

Parameters:

thisHttpBase - the http server.

Throws:

java.lang.Exception - any error.

messageToBus

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

Add the message to the message bus queue for subsequent processing.

Parameters:

ro - the request object to add.

adminKey - the server admin key.

Returns:

true if 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.

addMessageMetrics

protected void addMessageMetrics(MethodInfo messageInfo,
                                 java.lang.String thePassword)
                          throws java.lang.Exception

Add metric or stat values for the message object.

Overrides:

addMessageMetrics in class Service

Parameters:

messageInfo - the message info with the message object.

thePassword - the service password.

Throws:

java.lang.Exception - any error.

autoManFault

protected void autoManFault(Link_NM message)
                     throws java.lang.Exception

Add the fault tree to the autonomic manager queue for processing. Remove the existing message if it exists, so there is no repeat.

Parameters:

message - the whole fault tree.

Throws:

java.lang.Exception - any error.

allServiceMetrics

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

Get the stats for all services.

Parameters:

adminKey - the admin key of this server.

Returns:

list of stats objects, one for each service, key is service id.

serviceMetrics

public Metrics serviceMetrics(java.lang.String serviceID,
                              java.lang.String serverAdminKey)
                       throws PasswordException,
                              ServiceException,
                              java.lang.Exception

Get the stats for the specified service.

Parameters:

serviceID - the id of the service to retrieve the stats for.

serverAdminKey - the admin key of this server.

Returns:

the stats object.

Throws:

PasswordException - incorrect admin key.

ServiceException - service processing error.

java.lang.Exception - any other error.

isBlockedService

protected boolean isBlockedService(java.lang.String serviceID)

Return true if the service is blocked from access.

Parameters:

serviceID - the uuid of the service to check.

Returns:

true if blocked from access, false otherwise.

blockService

public boolean blockService(java.lang.String serviceUuid,
                            java.lang.String adminKey)
                     throws PasswordException

Block the service from being accessed. This only applies to a service running directly on the server.

Parameters:

serviceUuid - the uuid of the service to block.

adminKey - the unique admin key for the service.

Returns:

true if blocked, false otherwise.

Throws:

PasswordException - incorrect admin key.

unblockService

public boolean unblockService(java.lang.String serviceUuid,
                              java.lang.String adminKey)
                       throws PasswordException

Unblock the service to re-allow access. This only applies to a service running directly on the server.

Parameters:

serviceUuid - the uuid of the service to unblock.

adminKey - the unique admin key for the service.

Returns:

true if unblocked, false otherwise.

Throws:

PasswordException - incorrect admin key.

createServiceWrapper

protected ServiceWrapperDef createServiceWrapper(java.lang.Object serviceObj,
                                                 java.lang.String serviceName,
                                                 java.lang.String serviceType,
                                                 java.util.ArrayList<java.lang.String> jarFiles,
                                                 org.licas_xml.abs.Element adminXml)
                                          throws java.lang.Exception

Create a service wrapper for storing the service object. This version returns an autonomic manager if the service object is derived from Auto, or a service wrapper if it is not. Only base services added to the server can be wrapped with an autonomic manager and then only if they also implement the auto logic. There is a default AutonomicManagerDefault class with empty monitoring modules, or you can declare a different autonomic manager in your admin document and load those classes instead.

Overrides:

createServiceWrapper in class Service

Parameters:

serviceObj - the service object that is wrapped and managed.

serviceName - the name of the service.

serviceType - the type of the service.

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

adminXml - an admin document describing the service wrapper. This is probably empty, but it can declare different manager classes, config or policy scripts, for example.

Returns:

the correct service wrapper type.

Throws:

java.lang.Exception - any error.

getServiceWrapper

protected 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, but 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.

clearNetwork

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

Remove all components of the network currently running on this server.

Parameters:

adminKey - the service key for this server.

Throws:

java.lang.Exception - any error.

clearNetwork

public void clearNetwork(java.util.ArrayList<java.lang.String> serviceTypes,
                         boolean keepRemove,
                         java.lang.String adminKey)
                  throws java.lang.Exception

Remove all components of the network currently running on this server, but only of the specified service type. This can also specify to only keep services of the specified type.

Parameters:

serviceTypes - list of service types to keep or remove.

keepRemove - if true types to keep, if false types to remove.

adminKey - the service key for this server.

Throws:

java.lang.Exception - any error.

isStoredService

protected boolean isStoredService(java.lang.String theServiceID)

Return true if the service id is stored for a loaded service.

Parameters:

theServiceID - the unique service id.

Returns:

true if registered for a loaded service of false otherwise.

messageBus

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

Execute a call on the system message bus. This passes the message to a queue on the server from where it gets selected for processing by a service.

Specified by:

messageBus in interface BusDef

Parameters:

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

Returns:

Object the reply to the call.

Throws:

java.lang.Exception - any error.

executeServiceTypeAsync

public void executeServiceTypeAsync(java.lang.String serviceType,
                                    MethodInfo methodInfo)
                             throws java.lang.Exception

Execute an asynchronous method on the server, or a service type known by the server. This method calls executeServerService to invoke the methodInfo spec. The asynchronous call does not return a value, thereby freeing the client sooner. After executing the method, it instead saves any reply to a messageStore under the methodInfo's communicationID. This version forces a return type of Element on the method it invokes. If that is not correct the method to invoke will not be found.

Parameters:

serviceType - the service type on the server, see executeServiceType.

methodInfo - this is the actual method call as it would be invoked from any place. It requires the correct method name and parameter list.

Throws:

java.lang.Exception - any error.

executeServiceType

public org.licas_xml.abs.Element executeServiceType(java.lang.String serviceType,
                                                    MethodInfo methodInfo)
                                             throws java.lang.Exception

Execute a synchronous method on a service type known by the server and probably owned locally. This method calls executeServerService to invoke the parameter methodInfo spec. This version forces a return type of Element on the method it invokes. If that is not correct the method to invoke will not be found.

Parameters:

serviceType - the service type on the server. For example, the server search type is specified as MetaConst.SEARCHMETADATA, SEARCHAUTODATA, or SEARCHWEBFOLDER, SEARCHALLWEB. A metadata search queries all of the service metadata, and a web folder search queries the server's root web directory for matching text documents. Only services owned by the server are recognised by this method call. To execute on a service type in general, you replace the service name by it's type in the service URI and make a standard call through the system. Then any services subscribed to reply can process the message.

methodInfo - this is the actual method description as it would be invoked from any place. It requires the correct method name and parameter list. It is not restricted to the two search types, but the further programming might be required to add other ones. The invoked method is assumed to return XML elements only.

Returns:

the reply as an Element.

Throws:

java.lang.Exception - any error.

subscribe

public boolean subscribe(WorkInfo workInfo)
                  throws java.lang.Exception

Subscribe to receive information from an Information service.

Specified by:

subscribe in interface PublishSubscribeDef

Parameters:

workInfo - new client details. It must include the keyword list and the method to reply with.

1. A list of descriptive keywords and topic to match with.
2. Details of the client method to reply with if a service work matches with the keywords request.

If getClientURI() is empty, then the request is ignored. It must also contain a parameter list of size 1, that is either an Object or a WorkInfo object, as that is what will be sent as a reply.

Returns:

true if service request registered, false if keyword overlap.

Throws:

java.lang.Exception - any error.

unsubscribe

public void unsubscribe(KeywordInfo keyInfo,
                        org.licas_xml.abs.Element clientURI)
                 throws java.lang.Exception

Un-subscribe from a service.

Specified by:

unsubscribe in interface PublishSubscribeDef

Parameters:

keyInfo - list of descriptive keywords to uniquely identify the service.

clientURI - the client URI defines the request client.

Throws:

java.lang.Exception - any error.

publish

public boolean publish(WorkInfo workInfo)
                throws java.lang.Exception

Publish to provide information as an Information service.

Specified by:

publish in interface PublishSubscribeDef

Parameters:

workInfo - full work details, including an optional contract. The method description must include the client URI as this is what identifies the request. If getClientURI() is empty, then the request is ignored.

Returns:

true if work request registered, false if keyword overlap.

Throws:

java.lang.Exception - any error.

unpublish

public void unpublish(KeywordInfo keyInfo,
                      org.licas_xml.abs.Element serviceURI)
               throws java.lang.Exception

Un-publish to provide information.

Specified by:

unpublish in interface PublishSubscribeDef

Parameters:

keyInfo - list of descriptive keywords to uniquely identify the work.

serviceURI - the client URI defines the request service.

Throws:

java.lang.Exception - any error.

getAdminKey

public java.lang.String getAdminKey(java.lang.String serviceID,
                                    java.lang.String thisAdminKey)
                             throws PasswordException

Get the service key for the specified service. This is a child service of the server, or any service running on this server.

Parameters:

serviceID - the id of the service to retrieve the admin key for.

thisAdminKey - the admin key of this server.

Returns:

the service key for the requested service.

Throws:

PasswordException - incorrect admin key.

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 or false if it already exists.

getAllServiceMeta

public org.licas_xml.abs.Element getAllServiceMeta()
                                            throws java.lang.Exception

Get a default subset of the metadata for the full service list, for info purposes only.

Returns:

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

Throws:

java.lang.Exception - any error.

getAllServiceMeta

public org.licas_xml.abs.Element getAllServiceMeta(java.util.ArrayList<java.lang.String> serviceNames)
                                            throws java.lang.Exception

Get a default subset of the metadata for the specified list of services, for info purposes only.

Parameters:

serviceNames - list of services to retrieve.

Returns:

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

Throws:

java.lang.Exception - any error.

getServiceMeta

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

Get a default subset of the metadata for the service, for info purposes only.

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 org.licas_xml.abs.Element getServiceMeta(java.lang.String theServiceID,
                                                java.lang.String theAdminKey,
                                                java.util.ArrayList<java.lang.String> toInclude)
                                         throws java.lang.Exception

Get a default subset of the metadata for the service, plus other sections. This is instead of returning the full metadata description.

Parameters:

theServiceID - the unique id of the service to retrieve metadata for.

theAdminKey - for administrator-level access to the service. The admin key for the server is also allowed here.

toInclude - list of additional meta parts to return. See the ServiceMeta class for a description of the field names.

Returns:

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

Throws:

java.lang.Exception - any error.

getServiceMetaPart

public org.licas_xml.abs.Element getServiceMetaPart(java.lang.String theServiceID,
                                                    java.lang.String theAdminKey,
                                                    java.lang.String toInclude)
                                             throws java.lang.Exception

Retrieve just one part of the metadata description, not the whole object.

Parameters:

theServiceID - the unique id of the service to retrieve metadata for.

theAdminKey - for administrator-level access to the service. The admin key for the server is also allowed here.

toInclude - meta part to return. See the ServiceMeta class for a description of the field names.

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 full service metadata description from the repository.

Parameters:

theServiceID - the unique id of the service meta to retrieve.

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

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

Remove the service metadata from the 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.

hasServerPassword

protected boolean hasServerPassword()

Return true if the local server password is stored. Must be true here.

Overrides:

hasServerPassword in class Service

Returns:

true as this is the server.

getServerPassword

protected java.lang.String getServerPassword()
                                      throws java.lang.Exception

Get the local server password, which is the ESB password as well.

Overrides:

getServerPassword in class Service

Returns:

the local server password.

Throws:

java.lang.Exception - any error.

removeAllLinksTo

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

Remove all non-dynamic links to the specified service from all other services.

Overrides:

removeAllLinksTo in class Service

Parameters:

theServiceID - the unique id of the service to remove links to.

theAdminKey - the unique admin key for the service to remove links to.

Returns:

true if the admin key allows access, false otherwise.

Throws:

java.lang.Exception - any error.

getServiceTypes

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

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

Overrides:

getServiceTypes in class Service

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.

getServiceNamesPermission

protected java.util.ArrayList<java.lang.String> getServiceNamesPermission()

Return all registered service names. This method performs a second filtering stage, to return only the services that allow point-to-point access, or have not specified, for a service ID message.

Returns:

the service names for the service types list.

getServiceTypeNamesPermission

protected java.util.ArrayList<java.lang.String> getServiceTypeNamesPermission(java.util.ArrayList<java.lang.String> thisServiceTypes)
                                                                       throws LicasException

Return all registered service names for a list of service types. This method performs a second filtering stage, to return only the services that allow subscribe access, for a service type message.

Parameters:

thisServiceTypes - the service types list.

Returns:

the service names for the service types list.

Throws:

LicasException - if the service types input is null.

calculateRootNodes

public void calculateRootNodes(java.lang.String theAdminKey)

Calculate what nodes are root nodes, that is, are not children of any other nodes.

Parameters:

theAdminKey - the admin key for this server.

addRootNode

protected boolean addRootNode(java.lang.String theRootNode,
                              java.lang.String theAdminKey)

Add a service uuid to the list of root nodes. Note that the service itself must already be added to the server and this method is only to declare it as a root node in some hierarchical structure.

Parameters:

theRootNode - the uuid of the root service to add.

theAdminKey - the server admin key.

Returns:

true if the node is added or false otherwise.

removeRootNode

public boolean removeRootNode(java.lang.String theRootNode,
                              java.lang.String theAdminKey)
                       throws PasswordException

Remove a service uuid from the list of root nodes. Note that the service itself is not removed. This method is only to remove a root node in some hierarchical organisation structure.

Parameters:

theRootNode - the root node service uuid.

theAdminKey - the unique key for the service to remove.

Returns:

true if the node is removed or false otherwise.

Throws:

PasswordException - incorrect admin key.

getRootNodes

public java.util.ArrayList<java.lang.String> getRootNodes(java.lang.String theAdminKey)

Get a copy list of the root nodes.

Parameters:

theAdminKey - the unique key for the service to add.

Returns:

true if the node is added or false otherwise.

addLoader

public boolean addLoader(java.lang.String thePassword,
                         java.util.ArrayList<java.lang.String> uris)
                  throws java.lang.Exception

Add a new class loader from remote uris.

Parameters:

thePassword - the password to access this server.

uris - a list of remote uris to load the classes from.

Returns:

true if loader loaded.

Throws:

java.lang.Exception - any error.

addObject

public boolean addObject(java.lang.String thePassword,
                         java.lang.String className,
                         java.util.ArrayList<java.lang.String> uris)
                  throws java.lang.Exception

Create a new instance of an object, with no initialisation parameters. This loads the related java classes into the system.

Parameters:

thePassword - the password to access this server.

className - the name of the object class to load.

uris - a list of remote uris to load the classes from.

Returns:

true if loader loaded.

Throws:

java.lang.Exception - any error.

addParser

public boolean addParser(java.lang.String thePassword,
                         java.lang.String objectClass,
                         java.lang.String parserClass,
                         java.util.ArrayList<java.lang.String> uris,
                         java.util.ArrayList<java.lang.Object> params)
                  throws java.lang.Exception

Add a new parser to the parsers.

Parameters:

thePassword - the password to access this server.

objectClass - the class name of the object to parse.

parserClass - the class name of the parser.

uris - a list of remote uris to load the classes from.

params - any initialisation parameters.

Returns:

true if parser added.

Throws:

java.lang.Exception - any error.

removeParser

public boolean removeParser(java.lang.String thePassword,
                            java.lang.String objectClass)

Remove the parser from the parsers if it exists.

Parameters:

thePassword - the password to access this server.

objectClass - the class name of the object the parser parses.

Returns:

true if parser removed.

getServerSOA

public java.util.HashMap<java.lang.String,org.licas_xml.abs.Element> getServerSOA(java.lang.String theAdminKey)
                                                                           throws java.lang.Exception

Retrieve a description of the whole network structure in XML format.

Parameters:

theAdminKey - the unique key to allow admin operations on this server.

Returns:

a list of XML-based files that describe the network.

Throws:

java.lang.Exception - any error.

loadServerSOA

public java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>> loadServerSOA(java.lang.String dirPath,
                                                                                               java.lang.String theAdminKey)
                                                                                        throws java.lang.Exception

Load the network described by the list of XML-based documents onto the server.

Parameters:

dirPath - path to the local directory to read the files from. The network is identified as having a root Const.NETWORK element, while the links document has a root Const.LINKS element.

theAdminKey - the unique key to allow admin operations on this server.

Returns:

a list of the service ids with related passwords. Keys are the service ids of type string and values are password/service related values of type vector of Objects.

Throws:

java.lang.Exception - any error.

loadServerSOA

public java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>> loadServerSOA(java.util.HashMap<java.lang.String,org.licas_xml.abs.Element> networkXML,
                                                                                               java.lang.String theAdminKey)
                                                                                        throws java.lang.Exception

Load the network described by the list of XML-based documents onto the server.

Parameters:

networkXML - an XML description of the network. The network file is identified as having the key value Const.NETWORK element, while the links document has a root Const.LINKS element.

theAdminKey - the unique key to allow admin operations on this server.

Returns:

a list of the service ids with related passwords. Keys are the service ids of type string and values are password/service related values of type vector of Objects.

Throws:

java.lang.Exception - any error.

loadServiceFromXml

public boolean loadServiceFromXml(org.licas_xml.abs.Element serviceXml,
                                  java.lang.String theAdminKey)
                           throws java.lang.Exception

Create and load a serialized service from its XML description. Note that if this loads utility services through the script, these will not get registered with the server as they are created before the main service is added.

Parameters:

serviceXml - the full serialized description of the service, typically created by calling Service.serviceToXml on the service itself.

theAdminKey - the unique key to allow admin operations on this server.

Returns:

true if the services was created and loaded, false otherwise.

Throws:

java.lang.Exception - any error.

passwordsStateToXml

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

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

Overrides:

passwordsStateToXml in class Service

Parameters:

adminKey - the service admin key.

Returns:

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

Throws:

java.lang.Exception - any error.

getServerDetails

public org.licas_xml.abs.Element getServerDetails(java.lang.String theAdminKey)
                                           throws java.lang.Exception

Retrieve a description of the server itself in XML format. This is probably only passwords and links to other servers, so that it can be re-constructed.

Parameters:

theAdminKey - the unique key to allow admin operations on this server.

Returns:

a list of XML-based files that describe the network.

Throws:

java.lang.Exception - any error.

loadServerDetails

public boolean loadServerDetails(org.licas_xml.abs.Element serverXml,
                                 java.lang.String theAdminKey)
                          throws java.lang.Exception

Add the details as specified in the xml script to the server. This is probably only links to other servers at the moment.

Parameters:

serverXml - the server description to add.

theAdminKey - the unique key to allow admin operations on this server.

Returns:

true if added OK, or false if there was an error.

Throws:

java.lang.Exception - any error.

addPacketCommunicationID

public boolean addPacketCommunicationID(java.lang.String communicationID,
                                        int packetSize)
                                 throws java.lang.Exception

Add the communication id and packet info to the packetInfo structure.

Parameters:

communicationID - the id to identify the communication thread.

packetSize - the maximum size of the packet to send.

Returns:

true if the id and the file name are new and the file can be created.

Throws:

java.lang.Exception - any error.

addMessagePacket

public boolean addMessagePacket(java.lang.String communicationID,
                                java.lang.String packetObject)
                         throws java.lang.Exception

Add the message packet to the appropriate file as indicated by the communication id.

Parameters:

communicationID - the id to identify the communication thread.

packetObject - the next part of the message to save.

Returns:

true if the packet is successfully added to the file.

Throws:

java.lang.Exception - any error.

endOfMessage

public java.lang.Object endOfMessage(java.lang.String communicationID)
                              throws java.lang.Exception

Call this to indicate that the whole message has been sent and should now be executed.

Parameters:

communicationID - the id to identify the communication thread.

Returns:

the result of executing the method represented by the message.

Throws:

java.lang.Exception - any error.

getStats

public org.licas_xml.abs.Element getStats(java.lang.String queryType,
                                          java.lang.String adminKey)
                                   throws java.lang.Exception

Get the query stats.

Parameters:

queryType - the query engine service type on the server.

adminKey - the admin key for the server.

Returns:

the reply as an Element.

Throws:

java.lang.Exception - any error.

getSecureMethods

protected java.util.ArrayList<java.lang.String> getSecureMethods()

Get the list of methods that can be safely called on a secure server.

Overrides:

getSecureMethods in class AutoSecure

Returns:

the list of safe method names, but might still require passwords.

close

public void close()

Clean-up before shutting down the service.

Specified by:

close in interface java.lang.AutoCloseable

Overrides:

close in class Service