org.licas.server

## Class HttpServer

- java.lang.Object
- - org.licas.server.HttpServer

- All Implemented Interfaces:
    java.lang.AutoCloseable

      public class HttpServer
      extends java.lang.Object
      implements java.lang.AutoCloseable

  A lightweight HTTP server to host server side components. This is not the main class for interacting with the services, but it handles the remote requests received through the HTTP protocol and passes them onto the `ESB` class for processing. This base class also stores information on the exact address that the server is running on and controls both the blocking and non-blocking request threads that receive any remotely sent messages.

  NOTE: when this is created it also adds a keystore with a default (untrusted) licas certificate.

  Author:
    Kieran Greer

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static HttpServer` | `httpServer` The http server
    `protected PasswordHandler` | `passwordHandler` This stores and compares all passwords used by this service
    `protected static ServerConfig` | `serverConfig` The server config or setup info
    `protected boolean` | `shutDown` True if shutdown the service thread
    `protected java.lang.String` | `uuid` This is the ID of the component

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `HttpServer(ServerConfig theServerConfig)` Construct http server object.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `protected 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.
    `void` | `close()` Clean-up before shutting down the service.
    `protected java.lang.String` | `contactInfo()` Get a server administrator contact address, email or something.
    `protected ServiceWrapperDef` | `createServiceWrapper(Auto theService, 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 suitable for storing the service object.
    `java.lang.Object` | `execute(MethodInfo methodInfo)` Execute the specified method and return the result.
    `protected java.lang.Object` | `executeServer(MethodInfo methodInfo)` Execute the specified method and return the result.
    `protected ESB` | `getESB(java.lang.String adminKey)` Return the Enterprise Service Bus stored in this server.
    `Link_NM` | `getFaultsTree(java.lang.String adminKey)` Get the faults list tree.
    `protected static HttpServer` | `getHttpServer(java.lang.String adminKey)` Retrieve the static instance of the http server.
    `protected 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.
    `protected java.util.ArrayList<java.lang.String>` | `getPrivateMethods()` Get the list of public-level methods that should not be invoked externally, maybe from an interface.
    `protected java.util.ArrayList<java.lang.String>` | `getPublicMethods()` Get the list of methods that can be freely called on a Service in general, without even requiring a password.
    `protected java.util.ArrayList<java.lang.String>` | `getServerMethods()` Return true if the method can be freely called without a password.
    `protected java.lang.String` | `getServerPassword()` Get the local server password, which is the ESB password as well.
    `protected static java.lang.String` | `getServerURL()` Return the http address of the static http server.
    `protected ServiceWrapperDef` | `getServiceWrapper(java.lang.String serviceName, java.lang.String thePassword, java.lang.String adminKey)` Return the service wrapper for the related service name.
    `protected boolean` | `getThisShutDown()` Return a value indicating if this server should be shut down.
    `java.lang.String` | `getUUID()` Get the ID value.
    `protected boolean` | `hasJarFactory(java.lang.String thePassword)` Return true if this server is running a jar factory.
    `protected boolean` | `isAdminKey(java.lang.String theAdminKey)` Return true if the key passed in is this service's admin key.
    `protected boolean` | `isLocalIPAddress(java.lang.String theIPAddress)` Return true if the ip address represents a local server.
    `protected boolean` | `isPrivateMethod(java.lang.String methodName)` Return true if the method is a public-level method that should not be accessed externally.
    `boolean` | `isPublicMethod(java.lang.String methodName)` Return true if the method is a public method that can be freely called.
    `boolean` | `isRunning()` Return true if an enterprise service bus is stored and running in this server.
    `void` | `notifyOfFault(FaultDetails fault, java.lang.String adminKey)` This method should be called to notify the server about a problem or fault.
    `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)` Set the ESB and update with the config values.
    `boolean` | `setESB(java.lang.String serviceName, java.lang.String serviceType, org.licas_xml.abs.Element adminXml)` Set the ESB and update with the config values.
    `static boolean` | `setHttpServer(ServerConfig theServerConfig)` Create an instance of the http server.
    `void` | `setShutDown(java.lang.String thisAdminKey)` Set the shutdown variable to indicate that the thread should be stopped.
    `void` | `setUUID(java.lang.String thisUUID)` Set the ID value, but only if it is null, otherwise it is not changed.
    `protected void` | `shutDown()` Set the shut down variable to true
    `protected boolean` | `shutDown(java.lang.String theAdminKey)` Shut down the server and stop the request thread.
    `protected void` | `startRequestThread()` Start the request thread.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### uuid

          protected java.lang.String uuid

      This is the ID of the component

    - #### passwordHandler

          protected PasswordHandler passwordHandler

      This stores and compares all passwords used by this service

    - #### shutDown

          protected boolean shutDown

      True if shutdown the service thread

    - #### serverConfig

          protected static ServerConfig serverConfig

      The server config or setup info

    - #### httpServer

          protected static HttpServer httpServer

      The http server

  - ### Constructor Detail

    - #### HttpServer

          protected HttpServer(ServerConfig theServerConfig)
                        throws java.lang.Exception

      Construct http server object.
      Parameters:
        `theServerConfig` - the server config or setup info.
      Throws:
        `java.lang.Exception` - any error.

  - ### Method Detail

    - #### setHttpServer

          public static boolean setHttpServer(ServerConfig theServerConfig)
                                       throws java.lang.Exception

      Create an instance of the http server. Either this is the first instance or the admin key is correct for the current instance.
      Parameters:
        `theServerConfig` - the server config or setup info.
      Returns:
        true if the instance of the http server is created.
      Throws:
        `java.lang.Exception` - any error

    - #### getHttpServer

          protected static HttpServer getHttpServer(java.lang.String adminKey)

      Retrieve the static instance of the http server.
      Parameters:
        `adminKey` - the server admin key.
      Returns:
        the instance of the http server.

    - #### isRunning

          public 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.

    - #### setESB

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

      Set the ESB and update with the config values. Note that the ESB can only be added once, at the start of the server initialisation.
      Parameters:
        `serviceName` - the service name.
        `serviceType` - the service type.
        `adminXml` - the admin script.
      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)

      Set the ESB and update with the config values. Note that the ESB can only be added 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.

    - #### getESB

          protected ESB getESB(java.lang.String adminKey)

      Return the Enterprise Service Bus stored in this server.
      Parameters:
        `adminKey` - the admin key for this server.
      Returns:
        ESB the service manager.

    - #### hasJarFactory

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

    - #### getServerPassword

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

      Get the local server password, which is the ESB password as well.
      Returns:
        the local server password.
      Throws:
        `java.lang.Exception` - any error.

    - #### createServiceWrapper

          protected ServiceWrapperDef createServiceWrapper(Auto theService,
                                                           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 suitable for storing the service object. This version returns the default autonomic manager, or one described in the admin document. So you should extend this class and overwrite this method to return a different manager.
      Parameters:
        `theService` - the service that is wrapped and managed. Must be `Auto`-derived.
        `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 null, but might be a config and policy script, for example.
      Returns:
        the correct service wrapper type.
      Throws:
        `java.lang.Exception` - any error.

    - #### 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.
      Parameters:
        `adminKey` - server admin key.
      Returns:
        the value of faults.

    - #### 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.

    - #### startRequestThread

          protected void startRequestThread()

      Start the request thread.

    - #### getThisShutDown

          protected boolean getThisShutDown()

      Return a value indicating if this server should be shut down.
      Returns:
        a value if the server should be shut down.

    - #### shutDown

          protected void shutDown()

      Set the shut down variable to true

    - #### shutDown

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

    - #### contactInfo

          protected java.lang.String contactInfo()

      Get a server administrator contact address, email or something.
      Returns:
        a server contact address.

    - #### 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.

    - #### 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 overriden 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.

    - #### getJarForService

          protected FileObject getJarForService(java.lang.String jarName)
                                         throws java.lang.Exception

      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.
      Throws:
        `java.lang.Exception` - any error.

    - #### 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.
      Parameters:
        `methodInfo` - the method call description with all of the required information.
      Returns:
        the result of the method execution.
      Throws:
        `java.lang.Exception` - any error.

    - #### executeServer

          protected java.lang.Object executeServer(MethodInfo methodInfo)
                                            throws MethodNotFoundException,
                                                   java.lang.Exception

      Execute the specified method and return the result. This executes on the HttpServer directly.
      Parameters:
        `methodInfo` - the method call description with all of the required information.
      Returns:
        the reply, any object.
      Throws:
        `MethodNotFoundException` - for a method declaration mismatch.
        `java.lang.Exception` - any other error.

    - #### isAdminKey

          protected boolean isAdminKey(java.lang.String theAdminKey)

      Return true if the key passed in is this service's admin key.
      Parameters:
        `theAdminKey` - the key to check.
      Returns:
        true if this is the service key

    - #### setUUID

          public void setUUID(java.lang.String thisUUID)

      Set the ID value, but only if it is null, otherwise it is not changed. This method should probably not be called manually as the uuid is automatically set when the service is loaded as the service name.
      Parameters:
        `thisUUID` - the ID.

    - #### getUUID

          public java.lang.String getUUID()

      Get the ID value.
      Returns:
        the value of uuid.

    - #### isPublicMethod

          public boolean isPublicMethod(java.lang.String methodName)

      Return true if the method is a public method that can be freely called.
      Parameters:
        `methodName` - the name of the method.
      Returns:
        true if the method can be freely called.

    - #### isPrivateMethod

          protected boolean isPrivateMethod(java.lang.String methodName)

      Return true if the method is a public-level method that should not be accessed externally.
      Parameters:
        `methodName` - the name of the method.
      Returns:
        true if the method should not be called.

    - #### getServerMethods

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

      Return true if the method can be freely called without a password. Use by calling `isPublicMethod`.
      Returns:
        true if the method can be freely called.

    - #### getPublicMethods

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

      Get the list of methods that can be freely called on a Service in general, without even requiring a password.
      Returns:
        the list of safe method names, but might still require passwords.

    - #### getPrivateMethods

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

      Get the list of public-level methods that should not be invoked externally, maybe from an interface.
      Returns:
        the list of public-level method names that should not be accessible externally.

    - #### setShutDown

          public void setShutDown(java.lang.String thisAdminKey)

      Set the shutdown variable to indicate that the thread should be stopped.
      Parameters:
        `thisAdminKey` - the service key of this service.

    - #### checkAddress

          protected boolean checkAddress(java.lang.String host,
                                         int port)
                                  throws java.lang.Exception

      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.
      Throws:
        `java.lang.Exception` - any error.

    - #### isLocalIPAddress

          protected boolean isLocalIPAddress(java.lang.String theIPAddress)
                                      throws java.lang.Exception

      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.
      Throws:
        `java.lang.Exception` - any error.

    - #### getServerURL

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

    - #### close

          public void close()

      Clean-up before shutting down the service.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`