Package com.inductiveautomation.perspective.common.api

Class BrowserResource

java.lang.Object

com.inductiveautomation.perspective.common.api.BrowserResource

public class BrowserResource
extends 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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	BrowserResource.ResourceType

Field Summary

Fields

Modifier and Type	Field	Description
List<String>	dependencies	A list of dependencies that are required to load BEFORE this resource is loaded.
String	name	The name of the resource.
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.
String	versionHash	A string representing a specific version of the resource.

Constructor Summary

Constructors

Constructor	Description
BrowserResource(String name, String path, BrowserResource.ResourceType type)
BrowserResource(String name, String path, BrowserResource.ResourceType type, String versionHash)

Method Summary

Modifier and Type	Method	Description
static String	buildResourceUri(BrowserResource resource)	Builds an appropriate URI for a BrowserResource to be fetched when it's required by a component.
boolean	equals(Object o)
int	hashCode()
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

name

public String name

The name of the resource. Should be unique. For instance `momentjs` or `fancytablecss` and `fancytablejs`

path

public 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 String versionHash

A string representing a specific version of the resource.

dependencies

public List<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 Details

BrowserResource

public BrowserResource(String name,
 String path,
 BrowserResource.ResourceType type)

BrowserResource

public BrowserResource(String name,
 String path,
 BrowserResource.ResourceType type,
 String versionHash)

Parameters:

versionHash - a unique string representing the a fingerprint or hash for this particular resource

Method Details

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

buildResourceUri

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