DiscussionManagerInterface

Interface Description

This is an interface for coverage and dataset series managers. These managers shall facilitate registration of data in the database providing an easy-to-use interface for application programmers.

Managers are bound to a certain resource type, e.g. a DatasetSeries or a RectifiedStitchedMosaic. It suffices to have one manager per resource type as it can be invoked for many objects of this type.

acquireID(obj_id=None, fail=False)

This method shall acquire a valid and unique object ID and return it. The caller can provide a suggestion obj_id. In this case, the method shall try to acquire this object ID. The optional fail argument determines what the method shall do in case it cannot acquire the given obj_id. If it is set to True, the method shall raise an exception, otherwise it shall degrade gracefully returning a newly generated object ID.

The implementation should be able to guarantee that the acquired ID cannot be used by other threads of execution unless it is released and left unused. If it cannot assure this, the deviation shall be documented with a warning.

releaseID(obj_id)

This method shall release an object ID obj_id that has been acquired with acquireID_ beforehand. In case the object ID has been left unused, it shall be free to be acquired again.

create(obj_id=None, **kwargs)

This method shall create and return a coverage or dataset series wrapper from the attributes given in kwargs. The actual range of keyword arguments accepted may depend on the resource type and the implementation.

If the obj_id argument is omitted a new object ID shall be generated using the same mechanism as acquireID_. If the provided object ID is invalid or already in use, appropriate exceptions shall be raised.

update(obj_id, **kwargs)

This method shall update the coverage or dataset series with ID obj_id with new parameters provided as keyword arguments. The actual range of keyword arguments accepted may depend on the resource type and the implementation and should correlate with the arguments accepted by create_ as far as possible.

The method shall return the updated coverage or dataset series wrapper.

It shall raise NoSuchCoverage if there is no coverage or dataset series with ID obj_id.

delete(obj_id)

This method shall delete the coverage or dataset with ID obj_id.

It shall raise NoSuchCoverage if there is no coverage or dataset series with ID obj_id.

Interface Declaration

class ManagerInterface(RegisteredInterface):

    REGISTRY_CONF = {
        "name": "Manager Interface for EO Objects",
        "intf_id": "resources.coverages.interfaces.Manager",
        "binding_method": "kvp",
        "registry_keys": (
            "resources.coverages.interfaces.res_type",
        )
    }
    
    acquireID = Method(
        StringArg("obj_id", default=None),
        BoolArg("fail", default=False),
        returns = StringArg("@return")
    )
    
    releaseID = Method(
        StringArg("obj_id")
    )
    
    create = Method(
        StringArg("obj_id", default=None),
        KwArgs("kwargs"),
        returns = ObjectArg("@return")
    )
    
    update = Method(
        StringArg("obj_id"),
        KwArgs("kwargs"),
        returns = ObjectArg("@return")
    )
    
    delete = Method(
        StringArg("obj_id")
    )

Implementation Considerations

There should be one CoverageManager (one implementation of ManagerInterface) for each coverage type, i.e.

• PlainCoverageManager
• RectifiedDatasetManager
• ReferenceableDatasetManager
• RectifiedStitchedMosaicManager

and a DatasetSeriesManager.

Acquiring and Releasing IDs

In the first step, IDs will not be locked. So, the acquireID() method will just check if the desired ID, if any, is already in use and either return the desired ID or generate a new one. The call to releaseID() remains without effect.

In a future step, locking will be enabled, so that acquired IDs cannot be used anymore until they are released.

create() Method Signature

The create() method signature is defined quite generically. The implementation will accept at least the following keyword arguments all of which are optional:

location: An object implementing LocationInterface designating the location of the data file or record

local_path: The local path to a data file. Will be converted internally to a LocalPathWrapper object.

remote_path: The remote path to a data file. Will be converted internally to a RemotePathWrapper object.

ftp_host'', ''ftp_port'', ''ftp_user'', ''ftp_passwd: Parameters to define FTP server access. At least ftp_host'' is required if ''remote_path is used.

collection'', ''oid: The access parameters for a rasdaman array. Will be converted internally to a RasdamanArrayWrapper object.

ras_host'', ''ras_port'', ''ras_user'', ''ras_passwd'', ''ras_db: Parameter to define rasdaman database access. At least ras_host'' is required if ''collection'' and ''oid are used

md_location'', ''md_local_path'', ''md_remote_path: Parameters defining the location of a metadata file

eo_metadata: An EOMetadata object instance. Can be used as an alternative to md_location, etc.

geo_metadata: A GeospatialMetadata object instance. Required if this information cannot be read from the data object, e.g. for rasdaman arrays.

container: A RectifiedStitchedMosaicWrapper_' or '_DatasetSeriesWrapper object instance the new coverage shall be contained in. Applicable only for EO Coverages.

Usage Examples

Instances of the appropriate ManagerInterface implementation can be obtained from the registry, like in the following example:

from eoxserver.core.system import System

mgr = System.getRegistry().findAndBind(
    intf_id="resources.coverages.interfaces.Manager",
    params={
        "resources.coverages.interfaces.res_type": "eo.rect_dataset"
    }
)

The main intention of the managers is to facilitate the registration of new coverages. The typical workflow would be to

1. acquire an ID calling acquireID()
2. create a coverage using the acquired ID using create()
3. release the ID using releaseID()

If an arbitrary ID is sufficient, the calls to acquireID() and releaseID() can be omitted. Example:

coverage_id = mgr.acquireID("foo")

rect_dataset_wrapper = mgr.create(coverage_id, local_path="bar.tiff")

mgr.releaseID(coverageID)

or just

rect_dataset_wrapper = mgr.create(local_path="bar.tiff")