Package com.inductiveautomation.ignition.gateway.config

Class NamedResourceHandler<R>

java.lang.Object

com.inductiveautomation.ignition.common.lifecycle.AbstractLifecycle

com.inductiveautomation.ignition.gateway.config.NamedResourceHandler<R>

Type Parameters:

R - The type of the configuration object that is stored in the resources.

All Implemented Interfaces:

Lifecycle

Direct Known Subclasses:

FontManagerImpl, IconManagerImpl, ThemeManagerImpl

public abstract class NamedResourceHandler<R>
extends AbstractLifecycle

This class acts as an abstraction layer for handling named configuration resources. These resources are stored using the gateway's ConfigurationManager, and could be accessed directly using that API, but most subsystems find it more convenient to use this class to interact with their resources.

This class takes care of details like the following:

• Loading resources from the correct resource collection, so that subsystems don't need to worry about details like loading from core, local, or what the active deployment mode is.
• Using a ResourceCollectionLifecycleFactory to correctly listen for resource changes. These changes are packaged up and delivered to subclasses using the various on* methods (like onInitialResources(List) and onResourcesUpdated(List))
• Using the ResourceTypeMeta and it's ResourceCodec to encode and decode the configuration stored within the resource's config.json data file. By the time resources are delivered to subclasses of this method, they are already decoded into the appropriate configuration object and wrapped in a DecodedResource object. If resources cannot be decoded because of a DecodingException, they are simply treated as if they don't exist. This means that if a resource is updated and becomes un-decodable, it will be as if the resource was deleted (onResourceRemoved(DecodedResource) will be invoked. If the resource is later modified and becomes decode-able, it will be presented as if it is an added resource. (onResourceAdded(DecodedResource) will be invoked).
• Gracefully handles renaming resources, including detection and updating any references to the renamed resource.
• Understands and listens for changes to the gateway's redundancy role, and will automatically switch to using backup configuration objects (backupConfig.json) when the gateway is in a backup role.

To use this class, you can either:

• Extend it and override the various on* methods to handle resource changes
• Use the NamedResourceHandler.Builder by calling newBuilder(ResourceTypeMeta) to create an instance of this class, and provide callbacks for the various resource change events.

See Also:

• ResourceTypeMeta
• ConfigurationManager

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	NamedResourceHandler.Builder<R>

Field Summary

Fields

Modifier and Type	Field	Description
protected final ConfigurationManager	configManager
protected final org.slf4j.Logger	logger
protected final ResourceTypeMeta<R>	meta

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	NamedResourceHandler(ConfigurationManager configManager, RedundancyManager redundancyManager, ResourceTypeMeta<R> meta)
protected	NamedResourceHandler(GatewayContext context, ResourceTypeMeta<R> meta)

Method Summary

Modifier and Type	Method	Description
CompletableFuture<Void>	create(String name, R config)	Pass through for create(String, Object, String) with a null actor, indicating the source of the new resource is now known or unspecified.
CompletableFuture<Void>	create(String name, R config, String actor)	Pass through for create(String, Object, String, Consumer) with a null customizer, indicating that no additional customization is needed.
CompletableFuture<Void>	create(String name, R config, String actor, Consumer<ResourceBuilder> customizer)	Creates a new resource, with a UUID attribute derived by newUuid(Object).
protected Optional<DecodedResource<R>>	decode(Resource resource)
CompletableFuture<Void>	delete(String name)
CompletableFuture<Void>	delete(String name, ReferenceHandling referencePolicy)
protected boolean	filter(DecodedResource<R> resource)	This method is called to filter out resources that should not be included in the handler's list of resources.
Optional<DecodedResource<R>>	findResource(String name)	Find a resource by name.
List<DecodedResource<R>>	getResources()
protected boolean	isCaseSensitive()
protected boolean	isRenameAware()	Override this and return true (the default is false) to enable rename handling.
CompletableFuture<Void>	modify(String name, R config)	Modifies an existing resource.
CompletableFuture<Void>	modify(String name, R config, String actor)
CompletableFuture<Void>	modify(String name, R config, String actor, Consumer<ResourceBuilder> customizer)
static <R> NamedResourceHandler.Builder<R>	newBuilder(ResourceTypeMeta<R> meta)
protected @NotNull UUID	newUuid(R config)	Override if your config object contains/provides its own UUID.
protected void	onInitialResources(List<DecodedResource<R>> resources)	Called once at startup with the resource that are already present in the configuration collection.
protected void	onResourceAdded(DecodedResource<R> newResource)	Called once per each resource that is added.
protected void	onResourceRemoved(DecodedResource<R> removedResource)	Called for resources that are removed (or updated and then fail to parse).
protected void	onResourcesUpdated(List<DecodedResource<R>> resources)	Called each time the overall set of resources changes in any way.
protected void	onResourceUpdated(ModifiedResource<R> modifiedResource)	Called once per each resource that is updated.
protected void	onShutdown()
protected void	onStartup()
CompletableFuture<Void>	renameAndModify(String oldName, String newName, R config)	Renames and modifies an existing resource.
CompletableFuture<Void>	renameAndModify(String oldName, String newName, R config, String actor)
CompletableFuture<Void>	renameAndModify(String oldName, String newName, R config, String actor, Consumer<ResourceBuilder> customizer)
CompletableFuture<Void>	renameAndModify(String oldName, String newName, R config, String actor, Consumer<ResourceBuilder> customizer, ReferenceHandling referencePolicy)

Methods inherited from class com.inductiveautomation.ignition.common.lifecycle.AbstractLifecycle

isRunning, shutdown, startup

Methods inherited from class java.lang.Object

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

Field Details

logger

protected final org.slf4j.Logger logger

meta

protected final ResourceTypeMeta<R> meta

configManager

protected final ConfigurationManager configManager

Constructor Details

NamedResourceHandler

protected NamedResourceHandler(GatewayContext context,
 ResourceTypeMeta<R> meta)

NamedResourceHandler

protected NamedResourceHandler(ConfigurationManager configManager,
 @Nullable
 RedundancyManager redundancyManager,
 ResourceTypeMeta<R> meta)

Method Details

getResources

public List<DecodedResource<R>> getResources()

Returns:

an unmodifiable list of the resources currently in the configuration collection for the active mode.

findResource

public Optional<DecodedResource<R>> findResource(String name)

Find a resource by name.

Parameters:

name - The name of the resource. Case-sensitivity is determined by isCaseSensitive()

Returns:

An optional containing the decoded resource if it exists, or empty if it does not. The object inside the decoded resource is provided by ResourceTypeMeta.getCodec() that was passed to the constructor of this handler.

create

public CompletableFuture<Void> create(String name,
 R config)
                               throws PushException

Pass through for create(String, Object, String) with a null actor, indicating the source of the new resource is now known or unspecified.

Throws:

PushException

See Also:

• create(String, Object, String)

create

public CompletableFuture<Void> create(String name,
 R config,
 @Nullable
 String actor)
                               throws PushException

Pass through for create(String, Object, String, Consumer) with a null customizer, indicating that no additional customization is needed.

Throws:

PushException

See Also:

• create(String, Object, String, Consumer)

create

public CompletableFuture<Void> create(String name,
 R config,
 @Nullable
 String actor,
 Consumer<ResourceBuilder> customizer)
                               throws PushException

Creates a new resource, with a UUID attribute derived by newUuid(Object). The resource will be created in the collection specified by ResourceTypeMeta.getPreferredCollection()

Parameters:

name - The name of the resource to be created.

config - The configuration object to be stored in the resource.

actor - A string representing the actor responsible for the change. If null, "unknown" will be used.

customizer - A consumer that can be used to customize the resource before it is created.

Throws:

PushException - If a resource with the same name already exists.

See Also:

• ResourceCollectionManager.push(PushOperation)

newUuid

@NotNull
protected @NotNull UUID newUuid(R config)

Override if your config object contains/provides its own UUID.

Parameters:

config - the object that is about to be created in create(String, Object, String, Consumer)

Returns:

A random UUID by default.

See Also:

• UUID.randomUUID()
• ResourceUtil.getUuid(Resource)

modify

public CompletableFuture<Void> modify(String name,
 R config)
                               throws PushException

Modifies an existing resource. If the resource does not exist, this will throw a PushException. Will first fetch the existing resource, so that the resource is modified in its defining collection.

Throws:

PushException

modify

public CompletableFuture<Void> modify(String name,
 R config,
 String actor)
                               throws PushException

Throws:

PushException

modify

public CompletableFuture<Void> modify(String name,
 R config,
 @Nullable
 String actor,
 Consumer<ResourceBuilder> customizer)
                               throws PushException

Throws:

PushException

renameAndModify

public CompletableFuture<Void> renameAndModify(String oldName,
 String newName,
 R config)
                                        throws PushException

Renames and modifies an existing resource. This is actually a create followed by a delete. By using this method, the delete and create will be performed in a single, atomic push, which consolidates the updates to listeners.

Throws:

PushException

renameAndModify

public CompletableFuture<Void> renameAndModify(String oldName,
 String newName,
 R config,
 @Nullable
 String actor)
                                        throws PushException

Throws:

PushException

renameAndModify

public CompletableFuture<Void> renameAndModify(String oldName,
 String newName,
 R config,
 @Nullable
 String actor,
 Consumer<ResourceBuilder> customizer)
                                        throws PushException

Throws:

PushException

renameAndModify

public CompletableFuture<Void> renameAndModify(String oldName,
 String newName,
 R config,
 @Nullable
 String actor,
 Consumer<ResourceBuilder> customizer,
 ReferenceHandling referencePolicy)
                                        throws PushException

Throws:

PushException

delete

public CompletableFuture<Void> delete(String name)
                               throws PushException

Throws:

PushException

delete

public CompletableFuture<Void> delete(String name,
 ReferenceHandling referencePolicy)
                               throws PushException

Throws:

PushException

onInitialResources

protected void onInitialResources(List<DecodedResource<R>> resources)

Called once at startup with the resource that are already present in the configuration collection.

onResourceAdded

protected void onResourceAdded(DecodedResource<R> newResource)

Called once per each resource that is added.

onResourceUpdated

protected void onResourceUpdated(ModifiedResource<R> modifiedResource)

Called once per each resource that is updated.

Note that whether "rename" events are considered "updates" or "removes" and "adds" is determined by isRenameAware().

onResourceRemoved

protected void onResourceRemoved(DecodedResource<R> removedResource)

Called for resources that are removed (or updated and then fail to parse).

onResourcesUpdated

protected void onResourcesUpdated(List<DecodedResource<R>> resources)

Called each time the overall set of resources changes in any way. Called after added, updated, and removed are called.

onStartup

protected void onStartup()

Specified by:

onStartup in class AbstractLifecycle

onShutdown

protected void onShutdown()

Specified by:

onShutdown in class AbstractLifecycle

decode

protected Optional<DecodedResource<R>> decode(Resource resource)

filter

protected boolean filter(DecodedResource<R> resource)

This method is called to filter out resources that should not be included in the handler's list of resources. By default, this method filters out resources that are not enabled.

Note that resources which do not pass this filter (i.e. return false) will be "invisible" to the handler. For example, if a resource first passes the filter, and is loaded, but is then modified later and no longer passes, the handler will see this as a removal of that resource.

Parameters:

resource - the resource to process

Returns:

true if the resource should be included in the handler's list of resources, false otherwise.

isCaseSensitive

protected boolean isCaseSensitive()

Returns:

if the name handling in findResource(String) is considered case-sensitive (true) or not (false)

isRenameAware

protected boolean isRenameAware()

Override this and return true (the default is false) to enable rename handling. When enabled, the handler will use Resource "uuid"s to identify resources that have been renamed. So, rather than a rename looking like a "delete" event followed by an "add" event, it will instead be a onResourceUpdated(ModifiedResource) invocation where ModifiedResource.isRename() is true.

Note that if this is enabled, all resources must have a valid uuid attribute. Any resources missing this attribute will be treated as if they don't exist.

newBuilder

public static <R> NamedResourceHandler.Builder<R> newBuilder(@Nonnull
 ResourceTypeMeta<R> meta)