org.licas.util.classloader

## Class LoadObject

- java.lang.Object
- - org.licas.util.classloader.LoadObject

-     public class LoadObject
      extends java.lang.Object

  This class loads and returns a Java object. A `URLClassLoader` is used to try to load in a Java object from an external jar file. these get added to the list of loaders when you call `loadObject` to create an object instance, or when you call `addLoader` to add a new loader. One tip might be to add a set of the new jar files together.
  Author:
    Kieran Greer

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `LoadObject()` Creates a new instance of LoadObject

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.String` | `addJarPrefix(java.lang.String theJarFile)` Calculate what the correct prefix for the jar file paths is based on the uri of the server and add to the server uri.
    `static java.util.ArrayList<java.lang.String>` | `addJarPrefix(java.lang.String serverUri, java.util.ArrayList<java.lang.String> jarUris)` Calculate what the correct prefix for the jar file paths is based on the uri of the server and add to the jar file paths.
    `static java.lang.String` | `addJarPrefix(java.lang.String serverUri, java.lang.String theJarFile)` Calculate what the correct jar file path is based on the uri of the server and file path.
    `static void` | `addLoader(java.util.ArrayList<java.lang.String> uris)` Add the list of jar uris to the current loader.
    `protected static java.util.ArrayList<java.lang.Integer>` | `convertToParent(java.util.ArrayList<?> params)` Return indexes of parameters that should now be changed to the parent object.
    `static java.util.ArrayList<java.lang.String>` | `getAllClasses(java.lang.String jarUri, boolean rtnOnError)` Retrieve and return the names of all classes stored in the jar identified by the uri.
    `static boolean` | `getAllowNewLoaders()` Get the value indicating if url classloaders can be used.
    `static java.lang.Class` | `getClass(java.lang.String theClassName)` Retrieve a class instance of the class specified.
    `protected static boolean` | `isLegalClassFile(java.lang.String jarClassName)` Return true if the class name is a legal one for separate loading and creation.
    `static boolean` | `isLegalJarFile(java.lang.String jarFilePath)` Return true if the file path is a legal jar file type.
    `protected static boolean` | `isUrlLoader(java.lang.ClassLoader loader)` Return true if the classloader is a URL class loader.
    `static void` | `loadAllClasses()` Traverse through all currently stored class loaders and try to create an instance of each class.
    `protected static java.util.jar.JarFile` | `loadJarFile(java.lang.String jarUri)` Load and return the jar file from the specified uri.
    `static java.lang.Object` | `loadObject(java.util.ArrayList<java.lang.String> theJarUris, java.lang.String theClassName, java.util.ArrayList<?> params)` Create a new instance of the specified object and return.
    `static java.lang.Object` | `objStream(byte[] objBytes)` Use the jar loaders to read on a (base64) byte stream.
    `static java.lang.String` | `removeJarPrefix(java.lang.String theJarFile)` Remove additional jar file formatting that is used to define a jar file for a class loader.
    `static boolean` | `setAllowNewLoaders(boolean thisAllowNew, java.lang.String thisKey)` Set/change the value indicating if url classloaders can be used.
    `static boolean` | `setLoaderKey(java.lang.String thisKey)` Set the secret loader key.
    `protected static java.net.URL` | `uriToUrl(java.lang.String theUri)` Convert the uri spec into a URL.
    `protected static java.io.File` | `urlToFile(java.net.URL theUrl)` Convert the URL into a file object if it is valid.

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

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

- - ### Constructor Detail

    - #### LoadObject

          public LoadObject()

      Creates a new instance of LoadObject

  - ### Method Detail

    - #### isLegalJarFile

          public static boolean isLegalJarFile(java.lang.String jarFilePath)

      Return true if the file path is a legal jar file type. Currently only checks that the file ends with '.jar'.
      Parameters:
        `jarFilePath` - the jar file path.
      Returns:
        true if the file path is a jar file type.

    - #### isLegalClassFile

          protected static boolean isLegalClassFile(java.lang.String jarClassName)

      Return true if the class name is a legal one for separate loading and creation.
      Parameters:
        `jarClassName` - the name of the class in the jar file.
      Returns:
        if a new class can be created from it.

    - #### loadObject

          public static java.lang.Object loadObject(java.util.ArrayList<java.lang.String> theJarUris,
                                                    java.lang.String theClassName,
                                                    java.util.ArrayList<?> params)
                                             throws java.lang.Exception

      Create a new instance of the specified object and return.
      Parameters:
        `theJarUris` - uris from which the remote object can be loaded, only if needed.
        `theClassName` - the name of the class.
        `params` - initialisation parameters.
      Returns:
        the loaded object.
      Throws:
        `java.lang.Exception` - any error.

    - #### addLoader

          public static void addLoader(java.util.ArrayList<java.lang.String> uris)
                                throws java.lang.Exception

      Add the list of jar uris to the current loader.
      Parameters:
        `uris` - the list of jar uris.
      Throws:
        `java.lang.Exception` - any error.

    - #### loadJarFile

          protected static java.util.jar.JarFile loadJarFile(java.lang.String jarUri)
                                                      throws java.lang.Exception

      Load and return the jar file from the specified uri.
      Parameters:
        `jarUri` - the uri specification for the jar file.
      Returns:
        the loaded jar file.
      Throws:
        `java.lang.Exception` - any error.

    - #### loadAllClasses

          public static void loadAllClasses()
                                     throws java.lang.Exception

      Traverse through all currently stored class loaders and try to create an instance of each class.
      Throws:
        `java.lang.Exception` - any error.

    - #### getAllClasses

          public static java.util.ArrayList<java.lang.String> getAllClasses(java.lang.String jarUri,
                                                                            boolean rtnOnError)

      Retrieve and return the names of all classes stored in the jar identified by the uri. This does not add the jar as a permanent class loader. It only parses it to retrieve the class list. Use 'addLoader' or 'loadObject' to add as a permanent loader.
      Parameters:
        `jarUri` - the uri for the jar file.
        `rtnOnError` - if true, exit with the first load error, returning null. If false, try to load every class and ignore any errors.
      Returns:
        a list of all class names.

    - #### getClass

          public static java.lang.Class getClass(java.lang.String theClassName)

      Retrieve a class instance of the class specified.
      Parameters:
        `theClassName` - the binary or fully qualified name of the class.
      Returns:
        the class description or null if the class cannot be reflected.

    - #### objStream

          public static java.lang.Object objStream(byte[] objBytes)

      Use the jar loaders to read on a (base64) byte stream.
      Parameters:
        `objBytes` - the byte stream.
      Returns:
        the constructed object.

    - #### addJarPrefix

          public static java.lang.String addJarPrefix(java.lang.String theJarFile)
                                               throws java.lang.Exception

      Calculate what the correct prefix for the jar file paths is based on the uri of the server and add to the server uri.
      Parameters:
        `theJarFile` - the file path for the jar file.
      Returns:
        the full jar path specification.
      Throws:
        `java.lang.Exception` - any error.

    - #### addJarPrefix

          public static java.lang.String addJarPrefix(java.lang.String serverUri,
                                                      java.lang.String theJarFile)
                                               throws java.lang.Exception

      Calculate what the correct jar file path is based on the uri of the server and file path.
      Parameters:
        `serverUri` - the uri of the server to send the jar spec to.
        `theJarFile` - the file path for the jar file.
      Returns:
        the full jar path specification.
      Throws:
        `java.lang.Exception` - any error.

    - #### addJarPrefix

          public static java.util.ArrayList<java.lang.String> addJarPrefix(java.lang.String serverUri,
                                                                           java.util.ArrayList<java.lang.String> jarUris)
                                                                    throws java.lang.Exception

      Calculate what the correct prefix for the jar file paths is based on the uri of the server and add to the jar file paths.
      Parameters:
        `serverUri` - the uri of the server to send the jar spec to.
        `jarUris` - the jar file specifications.
      Returns:
        the jar file specifications with the prefix added.
      Throws:
        `java.lang.Exception` - any error.

    - #### removeJarPrefix

          public static java.lang.String removeJarPrefix(java.lang.String theJarFile)

      Remove additional jar file formatting that is used to define a jar file for a class loader. Try to keep only the file path itself.
      Parameters:
        `theJarFile` - the file path for the jar file.
      Returns:
        the full jar path specification.

    - #### uriToUrl

          protected static java.net.URL uriToUrl(java.lang.String theUri)

      Convert the uri spec into a URL. This only adds a file path, not a full jar file spec.
      Parameters:
        `theUri` - the uri description in String format.
      Returns:
        a URL generated from the uri.

    - #### urlToFile

          protected static java.io.File urlToFile(java.net.URL theUrl)

      Convert the URL into a file object if it is valid.
      Parameters:
        `theUrl` - the URL.
      Returns:
        a file object created from the specified path.

    - #### convertToParent

          protected static java.util.ArrayList<java.lang.Integer> convertToParent(java.util.ArrayList<?> params)

      Return indexes of parameters that should now be changed to the parent object.
      Parameters:
        `params` - the current parameters.
      Returns:
        the list of indexes to change to the parent object.

    - #### isUrlLoader

          protected static boolean isUrlLoader(java.lang.ClassLoader loader)

      Return true if the classloader is a URL class loader.
      Parameters:
        `loader` - the loader to check.
      Returns:
        true if a URL class loader.

    - #### setLoaderKey

          public static boolean setLoaderKey(java.lang.String thisKey)

      Set the secret loader key. Can only be set once.
      Parameters:
        `thisKey` - the key value.
      Returns:
        true if set, false if key already exists.

    - #### setAllowNewLoaders

          public static boolean setAllowNewLoaders(boolean thisAllowNew,
                                                   java.lang.String thisKey)

      Set/change the value indicating if url classloaders can be used.
      Parameters:
        `thisAllowNew` - true if allow adding new url classloaders, false if not allow, when only the setup loaders can be used.
        `thisKey` - the loader key to protect any changes.
      Returns:
        true if update made OK, false if loader key is not correct.

    - #### getAllowNewLoaders

          public static boolean getAllowNewLoaders()

      Get the value indicating if url classloaders can be used.
      Returns:
        the value of allowNewLoaders.