Interface WsLocationAdmin


  • public interface WsLocationAdmin
    Service for resolving symbolic locations to concrete/physical resources (e.g. the bootstrap configuration determines where resources reside for an active server instance).

    Resources are associated with a group, where the group functions as a pseudo-filesystem: a collection of locations that comprise a search path to use when locating resources by name.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      WsResource addLocation​(java.lang.String fileName, java.lang.String symbolicName)
      Add location to the registry of locations.
      WsResource asResource​(java.io.File file, boolean isFile)
      Create a WsResource for the provided file.
      java.io.File getBundleFile​(java.lang.Object caller, java.lang.String relativeBundlePath)
      Return a File with the given name (which may or may not exist, and may or may not be a directory) in the bundle's private working area.
      WsResource getRuntimeResource​(java.lang.String relativeRuntimePath)
      Return an WsResource object with the given name in the runtime install directory (wlp.install.dir).
      java.util.UUID getServerId()
      Returns a persistent unique identifier for the server.
      java.lang.String getServerName()
      Get a string representation of the configured server name.
      WsResource getServerOutputResource​(java.lang.String relativeServerPath)
      Return an WsResource object with the given name in the active server's configuration directory (server.output.dir).
      WsResource getServerResource​(java.lang.String relativeServerPath)
      Return an WsResource object with the given name in the active server's configuration directory (server.config.dir).
      WsResource getServerWorkareaResource​(java.lang.String relativeServerWorkareaPath)
      Return an WsResource object with the given name (which may or may not exist) in the active server's workarea.
      java.util.Iterator<WsResource> matchResource​(java.lang.String resourceGroupName, java.lang.String resourceRegex, int limit)
      Find the resource(s) matching the provided regular expression.
      java.lang.String printLocations​(boolean useLineBreaks)
      Print debug information about the configured locations for the current server.
      WsResource resolveResource​(java.lang.String resourceURI)
      Resolve the given resource URI (either an absolute URI, or a repository URI containing symbolics), and return an WsResource.
      WsResource resolveResource​(java.net.URI resourceURI)
      Resolve the given resource URI (either an absolute URI, or an liberty repository URI containing symbolics), and return an WsResource.
      java.lang.String resolveString​(java.lang.String string)
      Resolve all symbols in the given string URI.
    • Method Detail

      • printLocations

        java.lang.String printLocations​(boolean useLineBreaks)
        Print debug information about the configured locations for the current server.
        Parameters:
        formatOutput - If true, the output will be formatted and separated with line breaks, otherwise, output will be a comma-separated list.
        Returns:
        String containing a list of configured data locations.
      • getServerId

        java.util.UUID getServerId()
        Returns a persistent unique identifier for the server. The identifier is persisted across normal server restarts but is reset after a clean start.
        Returns:
        a unique identifier for the configured server
      • getServerName

        java.lang.String getServerName()
        Get a string representation of the configured server name.
        Returns:
        server name as a String
      • getBundleFile

        java.io.File getBundleFile​(java.lang.Object caller,
                                   java.lang.String relativeBundlePath)
        Return a File with the given name (which may or may not exist, and may or may not be a directory) in the bundle's private working area.

        This is a convenience method. It will use OSGi FrameworkUtil to find the Bundle used to load the caller's class, and then will call BundleContext.getDataFile(String) to create the File.

        Use forward slashes in the relative path.

        Parameters:
        caller - Object (this, or static's class) requesting a file in the bundle's private data area; can not be null
        relativeBundlePath - Relative path for inside of the bundle's private data area
        Returns:
        File inside the bundle's private data area
        Throws:
        MalformedLocationException - if relativeBundlePath is not relative (is an absolute path, a file URI, or starts with a symbol)
        java.lang.NullPointerException - if caller is null
      • getRuntimeResource

        WsResource getRuntimeResource​(java.lang.String relativeRuntimePath)
        Return an WsResource object with the given name in the runtime install directory (wlp.install.dir).

        Note: This method MUST not be used to resolve server resources since there is no relationship between the location of the runtime install and the location of server resources.

        Use forward slashes in the relative path.

        Parameters:
        relativeServerPath - Relative path for inside of the runtime install's directory, can not be null.
        Returns:
        WsResource inside the runtime install directory.
        Throws:
        MalformedLocationException - if relativeRuntimePath is not relative (is an absolute path, a file URI, or starts with a symbol), or if the path attempts to navigate to or above the parent (../).
        java.lang.IllegalArgumentException - if resource to be created already exists as a different type: i.e. if the resource uri indicates the resource should be a directory and the resource exists as a file, or vice versa.
      • getServerResource

        WsResource getServerResource​(java.lang.String relativeServerPath)
        Return an WsResource object with the given name in the active server's configuration directory (server.config.dir).

        Note: Anything generated by the server should be created using getServerOutputResource(java.lang.String). "Internal" data should be created using getServerWorkareaResource(String).

        Use forward slashes in the relative path.

        A File object for the base directory of the public server area can be obtained by calling this method with an empty string as filename.

        Parameters:
        relativeServerPath - Relative path for inside of the server's directory, can not be null.
        Returns:
        WsResource inside the server's configuration directory.
        Throws:
        MalformedLocationException - if relativeServerPath is not relative (is an absolute path, a file URI, or starts with a symbol), or if the path attempts to navigate to or above the parent (../).
        java.lang.IllegalArgumentException - if resource to be created already exists as a different type: i.e. if the resource uri indicates the resource should be a directory and the resource exists as a file, or vice versa.
      • getServerOutputResource

        WsResource getServerOutputResource​(java.lang.String relativeServerPath)
        Return an WsResource object with the given name in the active server's configuration directory (server.output.dir).

        Note: Server "working" data should be created/managed in either the bundle's data area, or the server's workarea. The server's root directory should contain only user-generated/controllable artifacts: Anything in the server dir should be treated as API.

        Use forward slashes in the relative path.

        A File object for the base directory of the public server area can be obtained by calling this method with an empty string as filename.

        Parameters:
        relativeServerPath - Relative path for inside of the server's directory, can not be null.
        Returns:
        WsResource inside the server's configuration directory.
        Throws:
        MalformedLocationException - if relativeServerPath is not relative (is an absolute path, a file URI, or starts with a symbol), or if the path attempts to navigate to or above the parent (../).
        java.lang.IllegalArgumentException - if resource to be created already exists as a different type: i.e. if the resource uri indicates the resource should be a directory and the resource exists as a file, or vice versa.
      • getServerWorkareaResource

        WsResource getServerWorkareaResource​(java.lang.String relativeServerWorkareaPath)
        Return an WsResource object with the given name (which may or may not exist) in the active server's workarea.

        Data in the server workarea will survive a refresh of the OSGi framework cache

        Best Practice: use a subdirectory (e.g. using the bundle's PID, or the config group name) to consolidate data associated w/ a particular bundle or subsystem, and reduce the likelihood of name collisions.

        Use forward slashes in the relative path.

        A File object for the base directory of the public server area can be obtained by calling this method with an empty string as filename.

        Parameters:
        relativeServerWorkareaPath - Relative path within the configured server's private workarea; can not be null
        Returns:
        WsResource inside the server's workarea
        Throws:
        MalformedLocationException - if relativeServerWorkareaPath is not relative (is an absolute path, a file URI, or starts with a symbol), or if the path attempts to navigate to or above the parent (../).
        java.lang.IllegalArgumentException - if resource to be created already exists as a different type: i.e. if the resource uri indicates the resource should be a directory and the resource exists as a file, or vice versa.
      • resolveResource

        WsResource resolveResource​(java.lang.String resourceURI)
        Resolve the given resource URI (either an absolute URI, or a repository URI containing symbolics), and return an WsResource.
        • file://blah
        • http://some.other.place/...
        • ${shared.app.dir}
        • ${shared.resource.dir}/security

        Use forward slashes in the resource URI.

        Parameters:
        resourceURI - Resource URI as a string
        Returns:
        WsResource representing the resource specified by the provided URI; may return null if the resourceURI contains an unknown/unresolvable symbol.
        Throws:
        MalformedLocationException - if the resourceURI is malformed
        java.lang.IllegalArgumentException - if the URI points to an existing resource of the wrong type (i.e. you specified a file, "a/b/c", but the resource already exists as a directory, "a/b/c/")
      • resolveResource

        WsResource resolveResource​(java.net.URI resourceURI)
        Resolve the given resource URI (either an absolute URI, or an liberty repository URI containing symbolics), and return an WsResource.
        • file://blah
        • http://some.other.place/...
        • ${wlp.install.dir}/applications

        Use forward slashes in the resource URI.

        Parameters:
        resourceURI - Resource URI
        Returns:
        WsResource representing the resource specified by the provided URI; may return null if the resourceURI contains an unknown/unresolvable symbol.
        Throws:
        MalformedLocationException - if the resourceURI is malformed
        java.lang.IllegalArgumentException - if the URI points to an existing resource of the wrong type (i.e. you specified a file, "a/b/c", but the resource already exists as a directory, "a/b/c/")
      • asResource

        WsResource asResource​(java.io.File file,
                              boolean isFile)
        Create a WsResource for the provided file.
        Parameters:
        file - The File object that should be converted to a WsResource
        isFile - If true, the file object should be treated as a file; if false, the file object should be treated as a directory.
        Returns:
        WsResource representing the provided file, or null if file argument is null.
        Throws:
        java.lang.IllegalArgumentException - if the File points to an existing resource of the wrong type (i.e. isFile is true, but the file object references a directory).
      • resolveString

        java.lang.String resolveString​(java.lang.String string)
        Resolve all symbols in the given string URI.
        file://blah file://blah
        ${shared.app.dir} /path/to/usr/shared/apps
        ${shared.resource.dir}/security /path/to/usr/shared/resources/security
        ${relativePathSymbol}/extra relative/extra
        Parameters:
        resourceURI - Resource URI as a string
        Returns:
        URI string for the resolved resource; may return null if the resourceURI contains an unknown/unresolvable symbol.
        Throws:
        MalformedLocationException - if the resourceURI is malformed
        java.lang.IllegalArgumentException - if the URI points to an existing resource of the wrong type (i.e. you specified a file, "a/b/c", but the resource already exists as a directory, "a/b/c/")
      • matchResource

        java.util.Iterator<WsResource> matchResource​(java.lang.String resourceGroupName,
                                                     java.lang.String resourceRegex,
                                                     int limit)
        Find the resource(s) matching the provided regular expression. Each element in the search path associated with a resource group will be queried for matches until the limit is reached.

        If a particular path is expected (e.g. a/b/c), include the path elements in the regular expression. Use forward slashes.

        The iterator will present resources in the order they were matched. If no resources were found, the iterator will have no elements.

        Parameters:
        resourceGroupName - Group of resources to resolve against: bundle, config, etc.
        resourceRegex - Regular expression describing matching resource URIs to find within the search path defined for the resourceGroup.
        limit - Maximum number of resources to match (0 implies no limit, 1 will only return first match, etc.)
        Returns:
        Iterator for the set/list of resources matching the provided regular expression.
        Throws:
        java.lang.IllegalArgumentException - if resource to be created already exists as a different type: i.e. if the resource uri indicates the resource should be a directory and the resource exists as a file, or vice versa. This throw may not occur until the element is reached while iterating.
      • addLocation

        WsResource addLocation​(java.lang.String fileName,
                               java.lang.String symbolicName)
        Add location to the registry of locations.
        Parameters:
        fileName - The name of the file that is the root of the location
        symbolicName - The symbolic name of this resource without the symbol decorations (e.g. productextension.extension.dir)
        Throws:
        java.lang.NullPointerException - if either the fileName or the symbolicName are null
        java.lang.IllegalArgumentException - if the named location exits and is a file