Package com.foreach.across.modules.web.resource

Class WebResourceRegistry

java.lang.Object
com.foreach.across.modules.web.resource.WebResourceRegistry
public class WebResourceRegistry extends Object

Registry for a set of web resources. Usually there is one registry per view. Used to specify things like css files, javascript files etc that should be loaded by the page. These can be added with a specific order.

Web resources are divided into separate named buckets. A single bucket usually corresponds with a location in a layout page, for example "the resources that should be added inside the <head> of a page".

As of version 3.2.0 the functionality of web resources and the registry has been thoroughly reworked for more flexibility.

A single web resource is represented by a WebResourceReference, the WebResource class itself is deprecated. The rendering of a resource is determined by the ViewElementBuilder attached to the reference. Default implementations for CSS, Javascript and META tags are available and can be created using the factory methods WebResource.css(), WebResource.javascript() or WebResource.meta().

In practice the easiest way to add web resources is by configuring them as rules to apply to the registry: * 


 webResourceRegistry.apply(
     WebResourceRule.add( WebResource.css( "@static:/MODULE_RESORCES/css/bootstrap.min.css" ) ).withKey( "bootstrap-min-css" ).toBucket( CSS ),
     WebResourceRule.add( WebResource.javascript( "bootstrap.min.js" ) ).withKey( "bootstrap-min-js" ).toBucket( JAVASCRIPT_PAGE_END ),
     WebResourceRule.add( WebResource.css().inline( "body {background-color: powderblue;}" ) ).withKey( "inline-body-blue" ).toBucket( CSS )
 );

A web resource can optionally be registered with a key. This is a String that identifies the resource in its bucket. Alternatively the ViewElementBuilder can implement WebResourceKeyProvider to provide a default key.

Since:
1.0.0
See Also:

  • Constructor Details

  • Method Details

    • getDefaultLocation

      @Deprecated public String getDefaultLocation()
      Deprecated.
      since 3.2.0
      Returns:
      The default location resources will be registered with.
      See Also:

    • setDefaultLocation

      @Deprecated public void setDefaultLocation(String defaultLocation)
      Deprecated.
      since 3.2.0 - it's advised to always specify a bucket name
      Parameters:
      defaultLocation - Default location to set.
      See Also:

    • add

      @Deprecated public void add(@NonNull @NonNull WebResource webResource)
      Deprecated.
      since 3.2.0 - replaced by WebResourceRule.add(ViewElementBuilder)
      Register a specific resource.
      Parameters:
      webResource - WebResource instance to add.

    • add

      @Deprecated public void add(String type, Object data)
      Deprecated.
      since 3.2.0 - replaced by WebResourceRule.add(ViewElementBuilder)
      Register a new resource with the default location. Since there is no key, any other resource of the same type with the same data will be replaced.
      Parameters:
      type - Type of the resource, see WebResource for constants.
      data - Data to register.

    • add

      @Deprecated public void add(String type, Object data, String location)
      Deprecated.
      since 3.2.0 - replaced by WebResourceRule.add(ViewElementBuilder)
      Registers a resource with the location specified. Since there is no key, any other resource of the same type with the same data will be replaced.
      Parameters:
      type - Type of the resource, see WebResource for constants.
      data - Data to register.
      location - Where the data is available.

    • addWithKey

      @Deprecated public void addWithKey(String type, String key, Object data)
      Deprecated.
      since 3.2.0 - replaced by WebResourceRule.add(ViewElementBuilder)
      Registers a resource under the given key. For complex interactions, it is often better to provide a key. Existing resources of this type with the same key will be replaced.
      Parameters:
      type - Type of the resource, see WebResource for constants.
      key - Unique key under which to register a resource.
      data - Data to register.

    • addWithKey

      @Deprecated public void addWithKey(String type, String key, Object data, String location)
      Deprecated.
      since 3.2.0 - replaced by WebResourceRule.add(ViewElementBuilder)
      Registers a resource under the given key. For complex interactions, it is often better to provide a key. Existing resources of this type with the same key will be replaced.
      Parameters:
      type - Type of the resource, see WebResource for constants.
      key - Unique key under which to register a resource.
      data - Data to register.

    • removeResource

      @Deprecated public void removeResource(Object data)
      Deprecated.
      since 3.2.0 - removing by "data" is not supported anymore
      Will remove all registered resources with the given content. Requires that the resource data equals() the requested data.
      Parameters:
      data - Content the resource should have.

    • removeResource

      @Deprecated public void removeResource(String type, Object data)
      Deprecated.
      since 3.2.0 - removing by "data" is not supported anymore
      Will remove all registered resources of that type with the given content.
      Parameters:
      type - Type of the resource, see WebResource for constants.
      data - Content the resource should have.

    • removeResourceWithKey

      public void removeResourceWithKey(@NonNull @NonNull String key)
      Will remove all resources registered under the key specified.
      Parameters:
      key - Key the resource is registered under.

    • removeResourceWithKeyFromBucket

      public Optional<WebResourceReference> removeResourceWithKeyFromBucket(@NonNull @NonNull String key, @NonNull @NonNull String bucket)
      Will remove the resource with a specific key from the bucket
      Parameters:
      key - Key the resource is registered under.
      bucket - Bucket name, see WebResource for constants.
      Returns:
      reference that was removed

    • addPackage

      public void addPackage(@NonNull @NonNull String... packageNames)
      Installs all resources attached to the packages with the names specified. This requires the packages to be registered in the attached WebResourcePackageManager.

      Note that a package will only be installed the first time, if it has been installed previously, it will be skipped.

      Parameters:
      packageNames - Names of the packages to install.

    • removePackage

      @Deprecated public void removePackage(@NonNull @NonNull String... packageNames)
      Deprecated.
      since 3.2.0 - might be removed in a future release as behaviour is hard to get consistent
      Will call the WebResourcePackage.uninstall(WebResourceRegistry) methods of the packages specified, if they are installed in the current registry. Note that the uninstalling should be used with care as it is hard to predict the exact behaviour.
      Parameters:
      packageNames - Names of the packages.

    • clear

      public void clear()
      Clears the entire registry, for all buckets.

    • clear

      public void clear(@NonNull @NonNull String bucket)
      Removes all resources in the given bucket.
      Parameters:
      bucket - Name of the bucket.

    • getResources

      @Deprecated public Collection<WebResource> getResources(String type)
      Deprecated.
      since 3.2.0 - replaced by getResourcesForBucket(String)
      Lists all resources for a given type.
      Parameters:
      type - Type of the resource.
      Returns:
      Collection of WebResource instances.

    • getResources

      @Deprecated public Collection<WebResource> getResources()
      Deprecated.
      since 3.2.0 - replaced by getResourcesForBucket(String)
      Lists all resources in this registry.
      Returns:
      Collection of WebResource instances.

    • getBuckets

      public Set<String> getBuckets()
      Return all bucket names in this registry.

    • getResourcesForBucket

      public WebResourceReferenceCollection getResourcesForBucket(@NonNull @NonNull String bucket)
      Return a WebResourceReferenceCollection from all resources in this registry for a specific bucket.
      Parameters:
      bucket - The bucket name.

    • merge

      public void merge(@NonNull @NonNull WebResourceRegistry registry)
      Merges all resources of the other registry in this one.
      Parameters:
      registry - Registry containing resource to be copied.

    • apply

      public void apply(@NonNull @NonNull WebResourceRule... webResourceRules)
      Will apply the set of WebResourceRule items to the registry.

    • apply

      public void apply(@NonNull @NonNull Collection<WebResourceRule> webResourceRules)
      Will apply the set of WebResourceRule items to the registry.

    • addResourceToBucket

      public boolean addResourceToBucket(@NonNull @NonNull WebResourceReference webResourceReference, @NonNull @NonNull String bucket)
      Adds a specific WebResourceReference to the specified bucket, creating the bucket if it does not exist. If there is already a reference with that key in the bucket, it will be replaced, see addResourceToBucket(WebResourceReference, String, boolean) if you want to control this behaviour.

    • addResourceToBucket

      public boolean addResourceToBucket(@NonNull @NonNull WebResourceReference webResourceReference, @NonNull @NonNull String bucket, boolean replaceIfExists)
      Add a WebResourceReference to the specified bucket, creating the bucket if it does not exist. The value of replaceIfExists will determine if a resource should be replaced if it is already present in the bucket. Replacing a resource will remove the original and put the new value in exactly the same spot. If replaceIfExists is false but a resource already has this key, the new resource will not be added at all and false will be returned.
      Parameters:
      webResourceReference - resource to add
      bucket - to which to add the resource
      replaceIfExists - true if the resource should be replaced
      Returns:
      true if resource was added or replaced, false if it already existed and has not been replaced

    • findResourceWithKeyInBucket

      public Optional<WebResourceReference> findResourceWithKeyInBucket(@NonNull @NonNull String key, @NonNull @NonNull String bucket)
      Find the resource reference registered under a specific key in a bucket.
      Parameters:
      key - of the resource
      bucket - name
      Returns:
      reference