Package dev.getelements.elements.rt

Interface ResourceService

All Known Implementing Classes:

TransactionalResourceService

public interface ResourceService

This is the service responsible for maintaining a set of Resource instances. This contains code to handle a the path hierarchy for the resources housed in the service. Resources can be added, moved, or deleted as needed by external services. Note that implementations of this interface should be considered thread safe. Each call must return or throw exceptions leaving the object in a consistent state. This may be accomplished using locking. All operations are to be considered atomic unless otherwise specified. Keep in mind that that while this instance may provided thread safety, the specification for Resource is not. Therefore, locking is necessary when performing operations on individual Resource instances themselves. This means that the internals of this service may lock the individual Resource instances to perform work as well. Created by patricktwohig on 7/24/15.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	ResourceService.Listing	Contains the association between the Path and ResourceId.
static interface	ResourceService.ResourceAcquisition	Acquires a Resource, guaranteeing it will stay in memory until this object is closed.
static interface	ResourceService.ResourceTransaction	Represents a transaction against a single instance of a Resource.
static interface	ResourceService.Unlink	The return-value for methods such as unlinkPath(Path) and unlinkPath(Path, Consumer)

Method Summary

Modifier and Type	Method	Description
ResourceService.ResourceAcquisition	acquire(ResourceId resourceId)	Acquires a Resource guaranteeing it will remain in-memory until the resource is released.
ResourceService.ResourceAcquisition	acquire(Path path)	Acquires a Resource guaranteeing it will remain in-memory until the resource is released.
ResourceService.ResourceTransaction	acquireWithTransaction(ResourceId resourceId)	Opens a ResourceService.ResourceTransaction.
ResourceService.ResourceTransaction	acquireWithTransaction(Path path)	Opens a ResourceService.ResourceTransaction.
ResourceService.ResourceAcquisition	addAndAcquireResource(Path path, Resource resource)	Adds an acquires this Resource.
void	addAndReleaseResource(Path path, Resource resource)	Adds a Resource to this resource service.
default void	destroy(ResourceId resourceId)	Removes a Resource and then immediately closes it.
default void	destroy(String resourceIdString)	Removes a Resource and then immediately closes it.
default List<ResourceId>	destroyResources(Path path, int max)	Destroys all Resources at the provided Path.
boolean	exists(ResourceId resourceId)	Deprecated. not used anywhere
long	getInMemoryResourceCount()
void	link(ResourceId sourceResourceId, Path destination)	Given the provided ResourceId, this will create an additional alias for the provided destination Path.
void	linkPath(Path source, Path destination)	Given the provided Path, this will create an additional Path alias for the provided source.
Stream<ResourceService.Listing>	listStream(Path path)	Returns a Stream<ResourceId> matching the provided Path.
Stream<Resource>	removeAllResources()	Removes all resources from.
default void	removeAndCloseAllResources()	Removes all resources from the service and closes them.
Resource	removeResource(ResourceId resourceId)	Removes a Resource instance from this resource service.
default Resource	removeResource(String resourceIdString)	Removes a Resource instance from this resource service.
default List<ResourceId>	removeResources(Path path, int max)	Removes all Resources linked with the provided Path.
List<ResourceId>	removeResources(Path path, int max, Consumer<Resource> removed)	Removes all Resources linked with the provided Path.
default void	start()	Called on start-up to ensure that the ResourceService has created and started any internal processes that it may need to perform its work.
default void	stop()	Releases all memory associated with this ResourceService.
default List<ResourceService.Unlink>	unlinkMultiple(Path path, int max)	Unlinks multiple Resources.
List<ResourceService.Unlink>	unlinkMultiple(Path path, int max, Consumer<Resource> removed)	Unlinks multiple Resources.
default ResourceService.Unlink	unlinkPath(Path path)	Similar to unlinkPath(Path, Consumer), however, this assumes that the final action should remove and destroy the associated Resource.
ResourceService.Unlink	unlinkPath(Path path, Consumer<Resource> removed)	Unlinks the Resource for the provided Path.

Method Details

start

default void start()

Called on start-up to ensure that the ResourceService has created and started any internal processes that it may need to perform its work.

stop

default void stop()

Releases all memory associated with this ResourceService. The actual action that happens here is dependent on the specific implementation. For in-memory implementations, this will simply close all resources and exit. For persistence-backed implementations this should flush all resources to disk before closing all. Once closed this instance may only be used after it has been restarted.

exists

@Deprecated
boolean exists(ResourceId resourceId)

Deprecated.

not used anywhere

Without affecting acquisition or releases, this performs a simple check to see if the Resource with the supplied ResourceId exists in this ResourceService.

Parameters:

resourceId - the ResourceId

Returns:

true if exists, false otherwise.

acquire

ResourceService.ResourceAcquisition acquire(Path path)

Acquires a Resource guaranteeing it will remain in-memory until the resource is released.

Returns:

the ResourceService.ResourceAcquisition

acquire

ResourceService.ResourceAcquisition acquire(ResourceId resourceId)

Acquires a Resource guaranteeing it will remain in-memory until the resource is released.

Returns:

the ResourceService.ResourceAcquisition

acquireWithTransaction

ResourceService.ResourceTransaction acquireWithTransaction(Path path)

Opens a ResourceService.ResourceTransaction.

Returns:

the ResourceService.ResourceTransaction

acquireWithTransaction

ResourceService.ResourceTransaction acquireWithTransaction(ResourceId resourceId)

Opens a ResourceService.ResourceTransaction.

Returns:

the ResourceService.ResourceTransaction

addAndReleaseResource

void addAndReleaseResource(Path path,
 Resource resource)

Adds a Resource to this resource service. This is used for the initial insert into the ResourceService. If linking to an additional Path is necessary, then the methods linkPath(Path, Path) or link(ResourceId, Path) must be used to perform additional aliasing operations. It is strongly recommended that newly inserted Resource instances be given a globally unique path initially, which can be thought of as the primary path, and then subsequent aliases or links be maintained, even if those particular Paths may collide. Once a Resource is passed ot this method, this ResourceService will take ownership of it. This means the the Resource may be closed after this call. Therefore, subsequent operations may require the Resource be fetched from serialization later for subsequent operations.

Parameters:

path - the initial path for the Resource

resource - the resource to insert

Throws:

DuplicateException - if a resource is already present

IllegalArgumentException - if the path is a wildcard path

addAndAcquireResource

ResourceService.ResourceAcquisition addAndAcquireResource(Path path,
 Resource resource)

Adds an acquires this Resource. This is used for the initial insert into the ResourceService. If linking to an additional Path is necessary, then the methods linkPath(Path, Path) or link(ResourceId, Path) must be used to perform additional aliasing operations. It is strongly recommended that newly inserted Resource instances be given a globally unique path initially, which can be thought of as the primary path, and then subsequent aliases or links be maintained, even if those particular Paths may collide. This is only safe to use with freshly created Resource instances whose ResourceId has never before been seen by the system.

Parameters:

path -

resource -

Returns:

the managed version of the supplied Resource

listStream

Stream<ResourceService.Listing> listStream(Path path)

Returns a Stream<ResourceId> matching the provided Path.

Parameters:

path - the Path to match

Returns:

a Stream<ResourceId>

link

void link(ResourceId sourceResourceId,
 Path destination)

Given the provided ResourceId, this will create an additional alias for the provided destination Path.

Parameters:

sourceResourceId -

destination -

Throws:

DuplicateException - if an alias already exists for the destination

ResourceNotFoundException - if the Resource can't be found

linkPath

void linkPath(Path source,
 Path destination)

Given the provided Path, this will create an additional Path alias for the provided source.

Parameters:

source - the source Path

destination - the destination Path

unlinkPath

default ResourceService.Unlink unlinkPath(Path path)

Similar to unlinkPath(Path, Consumer), however, this assumes that the final action should remove and destroy the associated Resource.

Parameters:

path - a Path to unlink

Returns:

true if the Resource associated with the Path was removed, false otherwise

unlinkPath

ResourceService.Unlink unlinkPath(Path path,
 Consumer<Resource> removed)

Unlinks the Resource for the provided Path. If the unlinked Path is the final path, then this will remove the Path from the ResourceService. If this Path is the last alias for the associated Resource, then the removed ResourceId will be passed to the supplied Consumer. The supplied Consumer will not be called if there still exist aliases for the associated Resource. Only one Resource may be unlinked at a time. Therefore, the supplied, Path most not be a wildcard path.

Parameters:

path - a Path to unlink

removed - a Consumer which will receive the removed Resource

Returns:

true if the Resource associated with the Path was removed, false otherwise

Throws:

IllegalArgumentException - if the path is a wildcard path

unlinkMultiple

default List<ResourceService.Unlink> unlinkMultiple(Path path,
 int max)

Unlinks multiple Resources. This accepts a Path, which may be a wildcard.

Parameters:

path -

max -

Returns:

unlinkMultiple

List<ResourceService.Unlink> unlinkMultiple(Path path,
 int max,
 Consumer<Resource> removed)

Unlinks multiple Resources. This accepts a Path, which may be a wildcard.

Parameters:

path - the path to remove

max - the maximum count to remove

removed - a Consumer<Resource> to process each removal

Returns:

the final ResourceService.Unlink operations

removeResource

Resource removeResource(ResourceId resourceId)

Removes a Resource instance from this resource service.

Parameters:

resourceId - the resourceId to the resource

Throws:

ResourceNotFoundException - if no resource exists at that path

IllegalArgumentException - if the path is a wildcard path

removeResource

default Resource removeResource(String resourceIdString)

Removes a Resource instance from this resource service.

Parameters:

resourceIdString - the path as a string

Returns:

the removed Resource

Throws:

IllegalArgumentException - if the path is a wildcard path

removeResources

default List<ResourceId> removeResources(Path path,
 int max)

Removes all Resources linked with the provided Path.

Parameters:

path - the Path for the resource.

max -

removeResources

List<ResourceId> removeResources(Path path,
 int max,
 Consumer<Resource> removed)

Removes all Resources linked with the provided Path.

Parameters:

path - the the Path for the resource.

max -

removed - a Consumer<Resource> which accepts the removed resource

destroy

default void destroy(ResourceId resourceId)

Removes a Resource and then immediately closes it.

Parameters:

resourceId -

Throws:

ResourceNotFoundException - if no resource exists at that path

IllegalArgumentException - if the path is a wildcard path

destroy

default void destroy(String resourceIdString)

Removes a Resource and then immediately closes it.

Parameters:

resourceIdString - the String representation of a ResourceId

Throws:

ResourceNotFoundException - if no resource exists at that path

IllegalArgumentException - if the path is a wildcard path

destroyResources

default List<ResourceId> destroyResources(Path path,
 int max)

Destroys all Resources at the provided Path.

Parameters:

path - the Path

removeAllResources

Stream<Resource> removeAllResources()

Removes all resources from. The returned Stream<Resource> returns any Resources that are still occupying memory and must be closed. The returned stream may be empty if all have been persisted. This operation may lock the whole ResourceService to accomplish its task.

removeAndCloseAllResources

default void removeAndCloseAllResources()

Removes all resources from the service and closes them. Any exceptions encountered are logged and all resources are attempted to be closed.

getInMemoryResourceCount

long getInMemoryResourceCount()