Package com.inductiveautomation.ignition.gateway.resourcecollection

Interface ResourceCollectionManager

All Known Subinterfaces:

ConfigurationManager, ProjectManager

public interface ResourceCollectionManager

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DEFAULT_NAME_PATTERN

Method Summary

Modifier and Type	Method	Description
void	addListener(ResourceCollectionListener listener)	Add a ResourceCollectionListener.
default String	copy(String name, String newName)	Create a copy of the resource collection named name, using newName as the new collection name, if possible.
void	create(String name, ResourceCollectionManifest manifest, List<Resource> resources)	Create a new resource collection with the provided manifest and resources.
void	createOrReplace(String name, ResourceCollectionManifest manifest, List<Resource> resources)	Create a new resource collection with the provided manifests and resources, or replace an existing collection by name if it already exists.
default String	createSafe(String name, ResourceCollectionManifest manifest, List<Resource> resources)	Create a new resource collection with the provided manifests and resources.
default String	createSafe(String name, ResourceCollectionManifest manifest, List<Resource> resources, String namePattern)	Create a new resource collection with the provided manifests and resources.
void	delete(String name)	Delete the resource collection named name, if it exists.
void	export(String name, OutputStream destination)	Export a copy of resource collection by writing the contents to the destination OutputStream.
default Optional<RuntimeResourceCollection>	find(String name)	Get a the RuntimeResourceCollection for the given name with all resources in all scopes, if it exists, if it exists, or else empty.
default Optional<RuntimeResourceCollection>	find(String name, int applicationScope)	Returns a RuntimeResourceCollection for the given name loaded with all resources that meet the given application scope, if it exists, or else empty.
Optional<RuntimeResourceCollection>	find(String name, ResourceFilter resourceFilter)	Returns a RuntimeResourceCollection for the given name containing only resources that pass the provided ResourceFilter, if it exists, or else empty.
Set<String>	getDefiningCollectionNames(ResourcePath resourcePath)	Return the set of resource collections which have a definition for the given resource path.
Map<String,ResourceCollectionManifest>	getManifests()	Get a Map of ResourceCollectionManifests for all current resource collections.
List<String>	getNames()	Get a List of all current resource collection names.
Optional<Resource>	getResource(String collectionName, ResourcePath resourcePath)	Find a resource defined in a specific collection, ignoring inheritance.
default boolean	isMutable(String collectionName)	Checks the mutability status of a resource collection.
List<ResourceCollectionDiff.AbsoluteDiff>	pull(List<Snapshot> snapshots)	Pull any changes for the given snapshots.
List<ResourceCollectionDiff.AbsoluteDiff>	pull(List<Snapshot> snapshots, ResourceFilter filter)	Pull any changes for the given snapshots, but only changes for resources that match the filter.
CompletableFuture<Void>	push(PushOperation pushOperation)	Attempt to push a list of ChangeOperations.
default CompletableFuture<Void>	push(List<ChangeOperation> changeOperations)	Push a list of changes, with no associated context object.
PartialPushResult	pushPartial(PushOperation operation)	Alternative version of push(List) that allows for some operations to succeed even if others fail.
void	removeListener(ResourceCollectionListener listener)	Remove a previously-registered ResourceCollectionListener.
CompletableFuture<Void>	requestScan()	Requests that a scan for changed resources on the filesystem be performed immediately.

Field Details

DEFAULT_NAME_PATTERN

static final String DEFAULT_NAME_PATTERN

See Also:

• Constant Field Values

Method Details

addListener

void addListener(ResourceCollectionListener listener)

Add a ResourceCollectionListener.

Parameters:

listener - the ResourceCollectionListener.

removeListener

void removeListener(ResourceCollectionListener listener)

Remove a previously-registered ResourceCollectionListener.

Parameters:

listener - the ResourceCollectionListener.

isMutable

default boolean isMutable(String collectionName)

Checks the mutability status of a resource collection. A mutable collection is one that can be modified by the user, through the disk, api, designer, scripting, etc. An immutable collection is managed programmatically, not represented on disk, and cannot be modified, removed, copied, or exported by the user or designer.

Parameters:

collectionName - the name of the resource collection to check.

Returns:

The mutability state of the given collection, if it exists. If the name doesn't represent a collection, this method will return true.

create

void create(String name,
 ResourceCollectionManifest manifest,
 List<Resource> resources)
     throws IllegalArgumentException,
IOException,
NameInUseException

Create a new resource collection with the provided manifest and resources. The new collection will be stored to disk and will be available for use immediately. Listeners will be notified.

Parameters:

name - the name of the resource collection to create.

manifest - the ResourceCollectionManifest.

resources - the resources, if any, to include in the collection

Throws:

IllegalArgumentException - if any of the resources indicate they belong to another collection other than name.

IOException - if the collection files could not be created.

NameInUseException - if a resource collection by name already exists.

See Also:

• ResourceCollectionListener

createSafe

default String createSafe(String name,
 ResourceCollectionManifest manifest,
 List<Resource> resources)
                   throws IllegalArgumentException,
IOException

Create a new resource collection with the provided manifests and resources.

If a collection by name already exists, the suffix "_N", where N increases monotonically from 1, is appended to name until a name that isn't already used is found.

Parameters:

name - the name of the collection to create.

manifest - the ResourceCollectionManifest.

resources - the resources, if any, to include in the collection.

Returns:

the actual name of the new collection that was created.

Throws:

IllegalArgumentException - if any of the resources indicate they belong to a collection other than name.

IOException - if the collection files could not be created.

createSafe

default String createSafe(String name,
 ResourceCollectionManifest manifest,
 List<Resource> resources,
 String namePattern)
                   throws IllegalArgumentException,
IOException

Create a new resource collection with the provided manifests and resources.

If a collection by name already exists the namePattern is applied to the name via String.format(String, Object...), with a monotonically increasing integer value supplied, until a suitable name is found.

Parameters:

name - the name of the collection to create.

manifest - the ResourceCollectionManifest.

resources - the resources, if any, to include in the collection.

namePattern - the name pattern to apply if name already exists.

Returns:

the actual name of the new collection that was created.

Throws:

IllegalArgumentException - if any of the resources indicate they belong to a collection other than name.

IOException - if the collection files could not be created.

createOrReplace

void createOrReplace(String name,
 ResourceCollectionManifest manifest,
 List<Resource> resources)
              throws IllegalArgumentException,
IOException,
ResourceCollectionImmutableException

Create a new resource collection with the provided manifests and resources, or replace an existing collection by name if it already exists.

Replacing an existing collection is modeled as a push(List) of create, modify, and delete ChangeOperations, as opposed to deleting the existing collection and creating a new one.

Parameters:

name - the name of the collection to create or replace.

manifest - the ResourceCollectionManifest.

resources - the resources, if any, to include in the resource collection.

Throws:

IllegalArgumentException - if any of the resources indicate they belong to a collection other than name.

IOException - if the resource collection files could not be created.

ResourceCollectionImmutableException - if the resource collection being replaced is immutable.

copy

default String copy(String name,
 String newName)
             throws IOException,
ResourceCollectionNotFoundException,
ResourceCollectionInvalidException,
ResourceCollectionImmutableException

Create a copy of the resource collection named name, using newName as the new collection name, if possible.

If newName already exists a suitable name will be chosen automatically via createSafe(String, ResourceCollectionManifest, List).

Parameters:

name - the name of the existing resource collection to copy.

newName - the name for the new resource collection.

Returns:

the actual name used for the new collection.

Throws:

IOException - if the resource collection files could not be created.

ResourceCollectionNotFoundException - if a collection name does not exist.

ResourceCollectionInvalidException - if the collection name exists but its configuration is not valid.

ResourceCollectionImmutableException - if the resource collection being copied is immutable.

delete

void delete(String name)
     throws IOException,
ResourceCollectionNotFoundException,
ResourceCollectionImmutableException

Delete the resource collection named name, if it exists.

Parameters:

name - the name of the resource collection to delete

Throws:

IOException - if the resource collection files could not be deleted.

ResourceCollectionNotFoundException - if a collection named name does not exist.

ResourceCollectionImmutableException - if the resource collection being deleted is immutable.

find

default Optional<RuntimeResourceCollection> find(String name)

Get a the RuntimeResourceCollection for the given name with all resources in all scopes, if it exists, if it exists, or else empty.

The resource collection returned will not have been validated. See RuntimeResourceCollection.validateOrThrow().

Parameters:

name - the name of the resource collection to find.

Returns:

the RuntimeResourceCollection for the given name with all resources in all scopes, or Optional.empty() if not found.

find

default Optional<RuntimeResourceCollection> find(@Nonnull
 String name,
 int applicationScope)

Returns a RuntimeResourceCollection for the given name loaded with all resources that meet the given application scope, if it exists, or else empty.

The resource collection returned will not have been validated. See RuntimeResourceCollection.validateOrThrow().

Parameters:

name - the name of the resource collection to find.

applicationScope - the ApplicationScope resources must belong to.

Returns:

a RuntimeResourceCollection for the given name loaded with all resources that meet the given application scope, or Optional.empty() if not found.

find

Optional<RuntimeResourceCollection> find(@Nonnull
 String name,
 ResourceFilter resourceFilter)

Returns a RuntimeResourceCollection for the given name containing only resources that pass the provided ResourceFilter, if it exists, or else empty.

The resource collection returned will not have been validated. See RuntimeResourceCollection.validateOrThrow().

Parameters:

name - the name of the resource collection to find.

resourceFilter - the ResourceFilter that all resources must pass

Returns:

a RuntimeResourceCollection for the given name containing only resources that pass the provided ResourceFilter, or Optional.empty() if not found.

getResource

Optional<Resource> getResource(String collectionName,
 ResourcePath resourcePath)

Find a resource defined in a specific collection, ignoring inheritance.

getDefiningCollectionNames

Set<String> getDefiningCollectionNames(ResourcePath resourcePath)

Return the set of resource collections which have a definition for the given resource path.

export

void export(String name,
 OutputStream destination)
     throws IOException,
ResourceCollectionNotFoundException,
ResourceCollectionImmutableException

Export a copy of resource collection by writing the contents to the destination OutputStream.

The bytes written are composed of a zip formatted resource collection folder that could be uncompressed and placed directly in a resource collection root directory (e.g projects/) resulting in a functional resource collection.

Parameters:

name - the name of the resource collection to export.

destination - an OutputStream to write the export to.

Throws:

IOException

ResourceCollectionNotFoundException

ResourceCollectionImmutableException

See Also:

• ProjectFileUtil.exportToZip(ResourceCollectionManifest, List, OutputStream)

getManifests

Map<String,ResourceCollectionManifest> getManifests()

Get a Map of ResourceCollectionManifests for all current resource collections.

Returns:

a Map of ResourceCollectionManifests, keyed by collection name.

getNames

List<String> getNames()

Get a List of all current resource collection names.

Returns:

a List of all current resource collection names.

push

default CompletableFuture<Void> push(List<ChangeOperation> changeOperations)
                              throws PushException

Push a list of changes, with no associated context object.

Returns after disk is updated but before listeners are notified. Wait on the returned future to ensure all listeners have been notified.

Returns:

a CompletableFuture that completes when all listeners have been notified.

Throws:

PushException

push

CompletableFuture<Void> push(PushOperation pushOperation)
                      throws PushException

Attempt to push a list of ChangeOperations.

If any changes conflict with the current state a PushException will be thrown. For example, a CREATE operation for a path that already exists, or a MODIFY or DELETE operation whose signature is not current.

It is expected that consumers of this API will then pull and resolve any conflicts before attempting to push again.

Returns after disk is updated but before listeners are notified. Wait on the returned future to ensure all listeners have been notified.

Parameters:

pushOperation - A push operation that contains a list of ChangeOperations to apply, with an optional context object.

Returns:

a CompletableFuture that completes when all listeners have been notified.

Throws:

PushException - if any changes conflict with the current state.

pushPartial

PartialPushResult pushPartial(PushOperation operation)

Alternative version of push(List) that allows for some operations to succeed even if others fail. Instead of throwing a PushException, this method returns a PartialPushResult that contains information about which changes succeeded and which failed, as well as the future that can be waited upon to ensure all listeners have been notified.

Important note: It is the responsibility of the caller to ensure that the operations are independent of one another. In other words, no one operation should rely on the success or failure of another operation. This is important because the validity checking done by this manager does not check for dependencies between operations.

pull

List<ResourceCollectionDiff.AbsoluteDiff> pull(List<Snapshot> snapshots)
                                        throws PullException

Pull any changes for the given snapshots.

Parameters:

snapshots - the Snapshots to pull changes for.

Returns:

ResourceCollectionDiffs for each Snapshot containing any resource diffs.

Throws:

PullException

pull

List<ResourceCollectionDiff.AbsoluteDiff> pull(List<Snapshot> snapshots,
 ResourceFilter filter)
                                        throws PullException

Pull any changes for the given snapshots, but only changes for resources that match the filter.

Parameters:

snapshots - the Snapshots to pull changes for.

filter - the ResourceFilter.

Returns:

ResourceCollectionDiff.AbsoluteDiffs for each Snapshot containing any resource diffs.

Throws:

PullException

requestScan

CompletableFuture<Void> requestScan()

Requests that a scan for changed resources on the filesystem be performed immediately. If this method is called while a scan is already in progress, a new scan will not be initiated and will complete when the current scan is done.

Returns:

a CompletableFuture that completes when a new scan or currently running scan has completed.