Class BrowserResource


  • public class BrowserResource
    extends java.lang.Object
    Model for a Perspective client dependency (aka - browser runtime dependency) required by one or more components.

    This class serves as a way of describing a client-side dependency that the Perspective Gateway may serve up to requesting client sessions when needed. BrowserResources dependencies are registered through the Perspective's common scoped ComponentRegistry, as part of a component's ComponentDescriptor. When a perspective session is launched, the set of component types utilized in that session's com.inductiveautomation.perspective.gateway.config.ProjectConfig is evaluated and the set of resources required by a project are sent from the gateway to the client. This set is built according to the 'name' value of the BrowserResource, such that a resource is added to the client before project startup if there is at least one component in the project requesting the resource.

    Since it is always less performant to load unwanted/duplicate resources, it's important for a 'name' to be unique in describing one specific resource type and path. So if your component(s) rely on an additional javascript library, you should create that BrowserResource just once, and then add it to all ComponentDescriptors where it's needed.

    Additionally, for optimal performance, you should provide a 'version hash' for each browser resource. The inclusion of the versionHash is utilized by the perspective system to enable caching of client-side resources. Without the versionHash, BrowserResources will not be cached and may significantly slow project loading time.
    Since:
    8.0
    • Field Summary

      Fields 
      Modifier and Type Field Description
      java.util.List<java.lang.String> dependencies
      A list of dependencies that are required to load BEFORE this resource is loaded.
      java.lang.String name
      The name of the resource.
      java.lang.String path
      Should be the full path, including the file extension, of the url as it's served from the ignition gateway address.
      BrowserResource.ResourceType type
      The type of resource required to be loaded before the component is mounted.
      java.lang.String versionHash
      A string representing a specific version of the resource.
    • Field Detail

      • name

        public java.lang.String name
        The name of the resource. Should be unique. For instance `momentjs` or `fancytablecss` and `fancytablejs`
      • path

        public java.lang.String path
        Should be the full path, including the file extension, of the url as it's served from the ignition gateway address. For example, a default ignition gateway with perspective module installed may serve resources from https://gateway.local.lan:8043/main/res/perspective/libs/moment.js. The gateway address would be everything up to and including the port. So the path of our mounted resources would be just the '/main/res/perspective/libs/moment.js' part.
      • type

        public BrowserResource.ResourceType type
        The type of resource required to be loaded before the component is mounted. Examples would be javascript libraries and stylesheets (css) that the component requires. The resource type impacts how and when the resource is loaded by the client. For instance, we may want to load CSS and Fonts before javascript.
      • versionHash

        public java.lang.String versionHash
        A string representing a specific version of the resource.
      • dependencies

        public java.util.List<java.lang.String> dependencies
        A list of dependencies that are required to load BEFORE this resource is loaded. These dependency strings should be the name of the resource required to load first. E.g., if your component requires two independent javascript libraries X and Y such that Y requires X being loaded before it can function, then Y should register a dependency that is the 'name' value of X's BrowserResource.
    • Constructor Detail

      • BrowserResource

        public BrowserResource​(java.lang.String name,
                               java.lang.String path,
                               BrowserResource.ResourceType type,
                               java.lang.String versionHash)
        Parameters:
        versionHash - a unique string representing the a fingerprint or hash for this particular resource
    • Method Detail

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • buildResourceUri

        public static java.lang.String buildResourceUri​(BrowserResource resource)
        Builds an appropriate URI for a BrowserResource to be fetched when it's required by a component. Generally, this means that if a resource is registered with a versionHash, that hash is injected into the name to allow cache-ability without the need to manually do cache invalidation when updates occur (for example). As a result, if using version hashes then either the 'production' filename must already include the hash in the form "LibName.hash.js" so that it's retrievable on request, or (if using the static resource servlet) the file can be dynamically located and returned by intercepting the request via the GatewayModuleHook#onMountedResourceRequest() method, which is called prior to returning resources. Currently only applies to JS and CSS resource types.
        Parameters:
        resource - the resource to build the path for
        Returns:
        the uri used to collect the resource at runtime
        Since:
        8.0.2