uk.ac.starlink.util

## Class Loader

- java.lang.Object
- - uk.ac.starlink.util.Loader

-     public class Loader
      extends java.lang.Object

  Provides utilities associated with loading resources.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `PROPERTIES_FILE` Name of the file in the user's home directory from which properties are loaded.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Loader()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `checkJ2se()` Checks that the JRE contains classes that you'd expect it to.
    `static void` | `checkJ2seVendor()` Checks the reported vendor for this J2SE.
    `static <T> T` | `getClassInstance(java.lang.String classSpec, java.lang.Class<T> type)` Attempts to obtain an instance of a class with a given name which is an instance of a given type.
    `static <T> java.util.List<T>` | `getClassInstances(java.lang.String[] defaultNames, java.lang.String propertyName, java.lang.Class<T> type)` Returns a list of class instances got from a combination of a default list of classnames and the name of a property which may contain a colon-separated list of other classnames.
    `static <T> java.util.List<T>` | `getClassInstances(java.lang.String propertyName, java.lang.Class<T> type)` Attempts to obtain instances of a class from a colon-separated list of classnames in a named system property.
    `static java.io.File` | `getPropertiesFile()` Returns the name of the file from which properties will be loaded by this class.
    `static boolean` | `is64Bit()` Tests whether the JVM appears to be 64-bit or not.
    `static void` | `loadLibrary(java.lang.String libname)` Loads a native library given its name.
    `static void` | `loadProperties()` Ensures that the user's customised properties have been loaded; these are read once from the file returned by the `getPropertiesFile()` method and incorporated into the System properties.
    `static void` | `setDefaultProperty(java.lang.String key, java.lang.String value)` Sets a system property to a given value unless it has already been set.
    `static void` | `setHttpAgent(java.lang.String productTokens)` Configures the "http.agent" system property.
    `static java.io.File` | `starjavaDirectory()` Returns the location of the main Starlink java directory which contains the lib, bin, etc, source directories and others.
    `static void` | `tweakGuiForMac()` Unless it's been set already, sets the value of the `apple.laf.useScreenMenuBar` system property to true.

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

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

- - ### Field Detail

    - #### PROPERTIES_FILE

          public static final java.lang.String PROPERTIES_FILE

      Name of the file in the user's home directory from which properties are loaded.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Loader

          public Loader()

  - ### Method Detail

    - #### starjavaDirectory

          public static java.io.File starjavaDirectory()

      Returns the location of the main Starlink java directory which contains the lib, bin, etc, source directories and others. It gets this by working out what jar file this class has been loaded from - there may be circumstances under which this doesn't work? but it's a best guess.

      If for some reason the directory cannot be located, null is returned.

      Returns:
        the top level starlink java directory, or `null` if it can't be found

    - #### loadLibrary

          public static void loadLibrary(java.lang.String libname)
                                  throws java.lang.SecurityException,
                                         java.lang.UnsatisfiedLinkError

      Loads a native library given its name. If it is not found on java.library.path, the architecture-specific lib directory in the installed Starlink system is searched.
      Parameters:
        `libname` - the name of the library (not including system-specifics such as 'lib' or '.so')
      Throws:
        `java.lang.SecurityException` - if a security manager exists and its `checkLink` method doesn't allow loading of the specified dynamic library
        `java.lang.UnsatisfiedLinkError` - if the library does not exist
      See Also:
        `System.loadLibrary(java.lang.String)`

    - #### getPropertiesFile

          public static java.io.File getPropertiesFile()
                                                throws java.lang.SecurityException

      Returns the name of the file from which properties will be loaded by this class.
      Returns:
        a file called `PROPERTIES_FILE` in the directory given by the System property "`user.home`".
      Throws:
        `java.lang.SecurityException`

    - #### loadProperties

          public static void loadProperties()

      Ensures that the user's customised properties have been loaded; these are read once from the file returned by the `getPropertiesFile()` method and incorporated into the System properties. Calling this method after the first time has no effect.
      See Also:
        `System.getProperties()`

    - #### getClassInstance

          public static <T> T getClassInstance(java.lang.String classSpec,
                                               java.lang.Class<T> type)

      Attempts to obtain an instance of a class with a given name which is an instance of a given type. If `className` is null or empty, null is returned directly. Otherwise, if the class `className` can be found using the default class loader, and if it is assignable from `type`, and if it has a no-arg constructor, an instance of it is constructed and returned. Otherwise, `null` is returned, and a message may be written through the logging system.

      A bean configuration parenthesis may be optionally appended, as per `BeanConfig`.

      Parameters:
        `classSpec` - name of the class to instantiate
        `type` - class which the instantiated class must be assignable from
      Returns:
        new `className` instance, or `null`

    - #### getClassInstances

          public static <T> java.util.List<T> getClassInstances(java.lang.String propertyName,
                                                                java.lang.Class<T> type)

      Attempts to obtain instances of a class from a colon-separated list of classnames in a named system property. If the named property does not exists or contains no strings, an empty list is returned. Otherwise, `getClassInstance(java.lang.String, java.lang.Class<T>)` is called on each colon-separated element of the property value, and if there is a non-null return, it is added to the return list. For colon-separated elements which do not correspond to usable classes, a message may be written through the logging system.
      Parameters:
        `propertyName` - name of a system property containing colon-separated classnames
        `type` - class which instantiated classes must be assignable from
      Returns:
        list of new `type` instances (may be empty, but not null)

    - #### getClassInstances

          public static <T> java.util.List<T> getClassInstances(java.lang.String[] defaultNames,
                                                                java.lang.String propertyName,
                                                                java.lang.Class<T> type)

      Returns a list of class instances got from a combination of a default list of classnames and the name of a property which may contain a colon-separated list of other classnames. The strings in each case must name classes which implement `type` and which have no-arg constructors.
      Parameters:
        `defaultNames` - array of string

    - #### is64Bit

          public static boolean is64Bit()

      Tests whether the JVM appears to be 64-bit or not. Not guaranteed reliable.
      Returns:
        true if the JVM appears to be running in 64 bits (if false, presumably it's 32 bits)

    - #### setDefaultProperty

          public static void setDefaultProperty(java.lang.String key,
                                                java.lang.String value)

      Sets a system property to a given value unless it has already been set. If it has a prior value, that is undisturbed. Potential security exceptions are caught and dealt with.
      Parameters:
        `key` - property name
        `value` - suggested property value

    - #### tweakGuiForMac

          public static void tweakGuiForMac()

      Unless it's been set already, sets the value of the `apple.laf.useScreenMenuBar` system property to true. This has the effect on Macintosh displays of causing menus to appear at the top of the screen rather than the top of the windows they belong in. This doesn't work on Dialog windows. Setting this property has no effect on non-Mac platforms. Probably(?) this call must be made before starting up the GUI (haven't got a Mac to hand, can't test it).

    - #### setHttpAgent

          public static void setHttpAgent(java.lang.String productTokens)

      Configures the "http.agent" system property. This sets the value of the "User-Agent" request header in outgoing HTTP requests. It is good practice to set this to identify the running application, so that external web servers can see who is using their services. If this property is not set, the User-Agent header will probably just report that it's Java. In the event that the http.agent property is already set on entry, there is no effect.

      According to RFC2616 sections 14.43 and 3.8, this string should be a whitespace-separated sequence of product tokens. A product token is of the form `product-name/product-version`.

      This method must be called before the current JVM has opened any HTTP connections to have an effect.

      Parameters:
        `productTokens` - one or more (whitespace-separated) name/version application identifiers
      See Also:
        RFC 2616, Section 14.43

    - #### checkJ2se

          public static void checkJ2se()
                                throws java.lang.ClassNotFoundException

      Checks that the JRE contains classes that you'd expect it to. This is chiefly useful for bailing out if we find ourself running in Gnu GCJ, which at time of writing is hopelessly incomplete. In the case that J2SE classes are missing, an exception will be thrown. The text of this exception will be a user-friendly message about what has gone wrong.
      Throws:
        `java.lang.ClassNotFoundException` - in case of a defective JRE

    - #### checkJ2seVendor

          public static void checkJ2seVendor()

      Checks the reported vendor for this J2SE. Depending on what is found, logging messages may be written. In particular, if it looks like GNU a warning-level message is emitted.