acme.services.Dispatcher.Dispatcher

class documentation

class Dispatcher:

Dispatcher class. Handles all requests and dispatches them to the appropriate handlers. This includes requests for resources, requests for resource creation, and requests for resource deletion.

Method	`checkRequestExpiration`	Check request expiration timeout if a request timeout is give.
Method	`checkResultExpiration`	Check result expiration timeout if a result timeout is given.
Method	`countDirectChildResources`	Return the number of all child resources of resource, optionally filtered by type.
Method	`countResources`	Return total number of resources. Optional filter by type.
Method	`createLocalResource`	Create a resource locally.
Method	`createResourceFromDict`	Create a resource from a JSON dictionary.
Method	`deleteChildResources`	Remove all child resources of a parent recursively.
Method	`deleteLocalResource`	Delete a resource from the CSE. Call deactivate() and deleted() callbacks on the resource.
Method	`deleteResource`	Delete a resource from the CSE.
Method	`directChildResourcesRI`	Return the resourceIdentifiers of all child resources of a resource, optionally filtered by type. An empty list is returned if no child resource could be found.
Method	`discoverChildren`	Discover child resources of a resource.
Method	`discoverResources`	Discover resources. This is the main function for resource discovery.
Method	`handleOperationExecutionTime`	Handle operation execution time and request expiration. If the OET is set then wait until the provided timestamp is reached.
Method	`hasDirectChildResource`	Check if a resource has a direct child resource with a given resourceID
Method	`initialize`	Initialize the Dispatcher.
Method	`notifyLocalResource`	Notify a local resource.
Method	`processCreateRequest`	Process a CREATE request. Create and register resource(s).
Method	`processDeleteRequest`	Process a DELETE request. Delete resource(s).
Method	`processNotifyRequest`	Process a NOTIFY request. Send notifications to resource(s).
Method	`processRetrieveRequest`	Process a RETRIEVE request. Retrieve and discover resource(s).
Method	`processUpdateRequest`	Process a UPDATE request. Update resource(s).
Method	`resourceTreeDict`	Recursively walk the results and build a sub-resource tree for each resource type.
Method	`retrieveDirectChildResources`	Return all child resources of a resource, optionally filtered by type. An empty list is returned if no child resource could be found.
Method	`retrieveLatestOldestInstance`	Get the latest or oldest x-Instance resource for a parent.
Method	`retrieveLocalResource`	Retrieve a resource locally.
Method	`retrieveResource`	Retrieve a resource locally or from remote CSE.
Method	`retrieveResourcesByType`	Retrieve all resources of a type.
Method	`retrieveResourceWithPermission`	Retrieve a resource and check access for an originator.
Method	`shutdown`	Shutdown the Dispatcher servide.
Method	`updateLocalResource`	Update a resource in the CSE. Call update() and updated() callbacks on the resource.
Method	`updateResourceFromDict`	Update a resource from a JSON dictionary.
Class Variable	`__slots__`	Slots of class attributes.
Class Variable	`factory`	Injected Factory instance.
Class Variable	`locationManager`	Injected LocationManager instance.
Class Variable	`registrationManager`	Injected RegistrationManager instance.
Class Variable	`remoteCSEManager`	Injected RemoteCSEManager instance.
Class Variable	`requestManager`	Injected RequestManager instance.
Class Variable	`scriptManager`	Injected ScriptManager instance.
Class Variable	`security`	Injected SecurityManager instance.
Class Variable	`semanticManager`	Injected SemanticManager instance.
Class Variable	`storage`	Injected Storage instance.
Class Variable	`timeManager`	Injected TimeManager instance.
Class Variable	`validator`	Injected Validator instance.
Instance Variable	`sortDiscoveryResources`	Sort the discovered resources.
Method	`_checkActiveCSESchedule`	Check if the CSE is currently active according to its schedule.
Method	`_checkHybridID`	Return a corrected id and srn in case this is a hybrid ID.
Method	`_childResourceTree`	Retrieve child resources of a resource and add them to a new target resource instance as "children"
Method	`_discoverResources`	Discover resources recursively. This is a helper function for discoverResources().
Method	`_getFanoutPointResource`	Check whether the target resource contains a fanoutPoint along its path is a fanoutPoint.
Method	`_getNotificationTargetSelfReferenceResource`	Check whether the target is a notificationTargetSelfReference virtual resource and return it.
Method	`_getPollingChannelURIResource`	Check whether the target is a PollingChannelURI resource and return it.
Method	`_getVirtualResource`	Check whether the target is a virtual resource and return it.
Method	`_latestOldestResource`	Check whether the target is a latest or oldest virtual resource and return it.
Method	`_matchResource`	Match a filter to a resource.
Method	`_resourcesToURIList`	Create a m2m:uril structure from a list of resources.
Method	`_resourceTreeReferences`	Retrieve child resource references of a resource and add them to a new target resource instance as "children"

def checkRequestExpiration(self, request: CSERequest): ¶

Check request expiration timeout if a request timeout is give.

Parameters
request:`CSERequest`	The request to check.

Raises
`REQUEST_TIMEOUT`	In case the request is expired

def checkResultExpiration(self, request: CSERequest): ¶

Check result expiration timeout if a result timeout is given.

Parameters
request:`CSERequest`	The request to check.

Raises
`REQUEST_TIMEOUT`	In case the result is expired
`BAD_REQUEST`	In case the request expiration timestamp is greater than the result expiration timestamp.

def countDirectChildResources(self, pi: str, ty: ResourceTypes | None = None) -> int: ¶

Return the number of all child resources of resource, optionally filtered by type.

Parameters
pi:`str`	The parent's resourceIdentifier.
ty:`ResourceTypes \| None`	The resource type to filter for.

Returns
`int`	Number of child resources.

def countResources(self, ty: ResourceTypes | tuple[ResourceTypes, ...] = None) -> int: ¶

Return total number of resources. Optional filter by type.

def createLocalResource(self, resource: Resource, parentResource: Resource, originator: str | None = None, rvi: str | None = None) -> Resource: ¶

Create a resource locally.

Parameters
resource:`Resource`	The resource to create.
parentResource:`Resource`	The parent resource.
originator:`str \| None`	The originator of the request.
rvi:`str \| None`	The release version identifier. This is only be present in a real CREATE request.

Returns
`Resource`	The created resource.

Raises
`TARGET_NOT_SUBSCRIBABLE`	If the parent resource is not subscribable.
`INVALID_CHILD_RESOURCE_TYPE`	If the child resource type is invalid.

def createResourceFromDict(self, dct: JSON, parent: str | Resource, ty: ResourceTypes, originator: str, checkCreation: bool = True, trustedSource: bool = False, preCreateCB: Callable[[Resource], None] | None = None) -> tuple[Resource | None, str, str, str]: ¶

Create a resource from a JSON dictionary.

Parameters
dct:`JSON`	The dictionary.
parent:`str \| Resource`	The parent ID or parent resource.
ty:`ResourceTypes`	The resource type.
originator:`str`	The originator.
checkCreation:`bool`	If True, then perform the resource creation check.
trustedSource:`bool`	If True, then the resource is created from a trusted source and some checks can be skipped. Note: Also access control is ignores.
preCreateCB:`Callable[[Resource], None] \| None`	A callback function that is called before the resource is created. The function takes the resource as an argument and can be used to modify the resource before it is created.

Returns
`tuple[Resource \| None, str, str, str]`	A tuple of (resource or None, resource ID, CSE-ID, parent ID).

Raises
`INTERNAL_SERVER_ERROR`	If an unknown/unsupported RSC is returned.
`ORIGINATOR_HAS_NO_PRIVILEGE`	If the originator has no privilege.

def deleteChildResources(self, parentResource: Resource, originator: str, ty: ResourceTypes | None = None, doDeleteCheck: bool | None = True): ¶

Remove all child resources of a parent recursively.

If ty is set only the resources of this type are removed.

def deleteLocalResource(self, resource: Resource, originator: str | None = None, withDeregistration: bool | None = False, parentResource: Resource | None = None, doDeleteCheck: bool | None = True): ¶

Delete a resource from the CSE. Call deactivate() and deleted() callbacks on the resource.

Parameters
resource:`Resource`	The resource to delete.
originator:`str \| None`	The originator of the request.
withDeregistration:`bool \| None`	If True, deregister the resource.
parentResource:`Resource \| None`	The parent resource.
doDeleteCheck:`bool \| None`	If True, call childRemoved() on the parent resource. Also, will call willbeDeactivated() on the resource.

def deleteResource(self, id: str, originator: str | None = None): ¶

Delete a resource from the CSE.

Parameters
id:`str`	The resource ID to delete.
originator:`str \| None`	The originator of the request. Defaults to None.

Raises
`OPERATION_NOT_ALLOWED`	If the resource is a CSEBase resource.
`NOT_FOUND`	If the resource is not found.
`ORIGINATOR_HAS_NO_PRIVILEGE`	If the originator has no DELETE access to the resource.

def directChildResourcesRI(self, pi: str, ty: ResourceTypes | list[ResourceTypes] | None = None) -> list[str]: ¶

Return the resourceIdentifiers of all child resources of a resource, optionally filtered by type. An empty list is returned if no child resource could be found.

Parameters
pi:`str`	The parent's resourceIdentifier.
ty:`ResourceTypes \| list[ResourceTypes] \| None`	The resource type or list of resource types to filter for.

Returns
`list[str]`	A list of retrieved resourceIdentifiers. This list might be empty.

def discoverChildren(self, id: str, resource: Resource, originator: str, filterCriteria: FilterCriteria, permission: Permission) -> list[Resource] | None: ¶

Discover child resources of a resource.

Parameters
id:`str`	The resourceIdentifier of the resource to discover the children for.
resource:`Resource`	The resource to discover the children for.
originator:`str`	The originator of the request.
filterCriteria:`FilterCriteria`	The filter criteria to use.
permission:`Permission`	The permission to check.

Returns
`list[Resource] \| None`	A list of child resources. This list might be empty.

def discoverResources(self, id: str, originator: str, filterCriteria: FilterCriteria | None = None, rootResource: Resource | None = None, permission: Permission | None = Permission.DISCOVERY) -> list[Resource]: ¶

Discover resources. This is the main function for resource discovery.

Parameters
id:`str`	The ID of the resource to start discovery from.
originator:`str`	The originator of the request.
filterCriteria:`FilterCriteria \| None`	The filter criteria.
rootResource:`Resource \| None`	The root resource for discovery.
permission:`Permission \| None`	The permission to use.

Returns
`list[Resource]`	A list of discovered resources.

def handleOperationExecutionTime(self, request: CSERequest): ¶

Handle operation execution time and request expiration. If the OET is set then wait until the provided timestamp is reached.

Parameters
request:`CSERequest`	The request to check.

def hasDirectChildResource(self, pi: str, ri: str) -> bool: ¶

Check if a resource has a direct child resource with a given resourceID

Parameters
pi:`str`	The parent's resourceIdentifier.
ri:`str`	The resourceIdentifier to check for.

Returns
`bool`	True if a direct child resource with the given resourceIdentifier exists, False otherwise.

def initialize(self): ¶

Initialize the Dispatcher.

def notifyLocalResource(self, ri: str, originator: str, content: JSON) -> Result: ¶

Notify a local resource.

Parameters
ri:`str`	The resourceIdentifier of the resource to notify.
originator:`str`	The originator of the request.
content:`JSON`	The notification content.

Returns
`Result`	Result object.

Raises
`ORIGINATOR_HAS_NO_PRIVILEGE`	If the originator has no NOTIFY access to the resource.

def processCreateRequest(self, request: CSERequest, originator: str | None = None, id: str | None = None) -> Result: ¶

Process a CREATE request. Create and register resource(s).

Parameters
request:`CSERequest`	The incoming request.
originator:`str \| None`	The requests originator.
id:`str \| None`	Optional ID of the request.

Returns
`Result`	Result object.

Raises
`BAD_REQUEST`	If the request is invalid.
`NOT_FOUND`	If the resource cannot be found.
`OPERATION_NOT_ALLOWED`	If the operation is not allowed.
`SECURITY_ASSOCIATION_REQUIRED`	If a security association is required.
`ORIGINATOR_HAS_NO_PRIVILEGE`	If the originator has no privilege.
`CONFLICT`	If the resource already exists.

def processDeleteRequest(self, request: CSERequest, originator: str, id: str | None = None) -> Result: ¶

Process a DELETE request. Delete resource(s).

Parameters
request:`CSERequest`	The incoming request.
originator:`str`	The requests originator.
id:`str \| None`	Optional ID of the request.

Returns
`Result`	Result object.

Raises
`NOT_FOUND`	If the resource cannot be found.
`ORIGINATOR_HAS_NO_PRIVILEGE`	If the originator has no privilege.

def processNotifyRequest(self, request: CSERequest, originator: str | None, id: str | None = None) -> Result: ¶

Process a NOTIFY request. Send notifications to resource(s).

Parameters
request:`CSERequest`	The incoming request.
originator:`str \| None`	The requests originator.
id:`str \| None`	Optional ID of the request.

Returns
`Result`	Result object.

Raises
`BAD_REQUEST`	If the request is invalid.
`ORIGINATOR_HAS_NO_PRIVILEGE`	If the originator has no privilege.

def processRetrieveRequest(self, request: CSERequest, originator: str, id: str | None = None) -> Result: ¶

Process a RETRIEVE request. Retrieve and discover resource(s).

Parameters
request:`CSERequest`	The incoming request.
originator:`str`	The requests originator.
id:`str \| None`	Optional ID of the request.

Returns
`Result`	Result object.

Raises
`BAD_REQUEST`	If the request is invalid.
`ORIGINATOR_HAS_NO_PRIVILEGE`	If the originator has no privilege.
`INTERNAL_SERVER_ERROR`	If an internal error occurred.

def processUpdateRequest(self, request: CSERequest, originator: str, id: str | None = None) -> Result: ¶

Process a UPDATE request. Update resource(s).

Parameters
request:`CSERequest`	The incoming request.
originator:`str`	The requests originator.
id:`str \| None`	Optional ID of the request.

Returns
`Result`	Result object.

Raises
`BAD_REQUEST`	If the request is invalid.
`NOT_FOUND`	If the resource cannot be found.
`OPERATION_NOT_ALLOWED`	If the operation is not allowed.
`ORIGINATOR_HAS_NO_PRIVILEGE`	If the originator has no privilege.

def resourceTreeDict(self, resources: list[Resource], targetResource: JSON) -> list[Resource]: ¶

Recursively walk the results and build a sub-resource tree for each resource type.

def retrieveDirectChildResources(self, pi: str, ty: ResourceTypes | list[ResourceTypes] | None = None) -> list[Resource]: ¶

Return all child resources of a resource, optionally filtered by type. An empty list is returned if no child resource could be found.

Parameters
pi:`str`	The parent's resourceIdentifier. This is the resourceID of resource.
ty:`ResourceTypes \| list[ResourceTypes] \| None`	The resource type or list of resource types to filter for.

Returns
`list[Resource]`	A list of retrieved `Resource` objects. This list might be empty.

def retrieveLatestOldestInstance(self, pi: str, ty: ResourceTypes, oldest: bool | None = False) -> Resource | None: ¶

Get the latest or oldest x-Instance resource for a parent.

This is done by searching through all resources once to find the fitting resource (parent + type) with the latest or oldest ct attribute.

Parameters
pi:`str`	parent resourceIdentifier
ty:`ResourceTypes`	resource type to look for
oldest:`bool \| None`	switch between oldest and latest search

Returns
`Resource \| None`	Resource

def retrieveLocalResource(self, ri: str | None = None, srn: str | None = None, originator: str | None = None, request: CSERequest | None = None) -> Resource: ¶

Retrieve a resource locally.

Parameters
ri:`str \| None`	The resource ID.
srn:`str \| None`	The structured resource name.
originator:`str \| None`	The originator of the request.
request:`CSERequest \| None`	The request.

Returns
`Resource`	The retrieved resource.

Raises
`NOT_FOUND`	If the resource cannot be found.

def retrieveResource(self, id: str, originator: str | None = None, request: CSERequest | None = None, postRetrieveHook: bool | None = False) -> Resource: ¶

Retrieve a resource locally or from remote CSE.

Parameters
id:`str`	If the id is in SP-relative format then first check whether this is for the local CSE. If yes, then adjust the ID and try to retrieve it. If no, then try to retrieve the resource from a connected (!) remote CSE.
originator:`str \| None`	The originator of the request.
request:`CSERequest \| None`	Undocumented
postRetrieveHook:`bool \| None`	Only when retrieving localls, invoke the Resource's willBeRetrieved() callback.

Returns
`Resource`	Result instance.

Raises
`NOT_FOUND`	If the resource cannot be found.

def retrieveResourcesByType(self, ty: ResourceTypes) -> list[Resource]: ¶

Retrieve all resources of a type.

Parameters
ty:`ResourceTypes`	Resouce type to search for.

Returns
`list[Resource]`	A list of retrieved `Resource` objects. This list might be empty.

def retrieveResourceWithPermission(self, ri: str, originator: str, permission: Permission) -> Resource: ¶

Retrieve a resource and check access for an originator.

Parameters
ri:`str`	Resource ID of the resource to be retrieved.
originator:`str`	The originator to check the permission for.
permission:`Permission`	The permission to check.

Returns
`Resource`	The retrieved resource.

Raises
`NOT_FOUND`	In case the resource could not be found.
`ORIGINATOR_HAS_NO_PRIVILEGE`	In case the originator has not the required permission to the resoruce.

def shutdown(self) -> bool: ¶

Shutdown the Dispatcher servide.

Returns
`bool`	Boolean indicating the success.

def updateLocalResource(self, resource: Resource, dct: JSON | None = None, doUpdateCheck: bool | None = True, originator: str | None = None) -> Resource: ¶

Update a resource in the CSE. Call update() and updated() callbacks on the resource.

Parameters
resource:`Resource`	Resource to update.
dct:`JSON \| None`	JSON dictionary with the updated attributes.
doUpdateCheck:`bool \| None`	Enable/disable a call to update().
originator:`str \| None`	The request's originator.

Returns
`Resource`	Updated resource.

def updateResourceFromDict(self, dct: JSON, id: str, originator: str | None = None, resource: Resource | None = None) -> Resource: ¶

Update a resource from a JSON dictionary.

Parameters
dct:`JSON`	The dictionary.
id:`str`	The resource ID.
originator:`str \| None`	The originator.
resource:`Resource \| None`	The resource to update.

Returns
`Resource`	The updated resource.

Raises
`INTERNAL_SERVER_ERROR`	If the resource cannot be updated.
`ORIGINATOR_HAS_NO_PRIVILEGE`	If the originator has no UPDATE privileges.

__slots__: tuple[str, ...] = ¶

Slots of class attributes.

factory: Factory = ¶

Injected Factory instance.

locationManager: LocationManager | None = ¶

Injected LocationManager instance.

registrationManager: RegistrationManager = ¶

Injected RegistrationManager instance.

remoteCSEManager: RemoteCSEManager | None = ¶

Injected RemoteCSEManager instance.

requestManager: RequestManager = ¶

Injected RequestManager instance.

scriptManager: ScriptManager = ¶

Injected ScriptManager instance.

security: SecurityManager = ¶

Injected SecurityManager instance.

semanticManager: SemanticManager | None = ¶

Injected SemanticManager instance.

storage: Storage = ¶

Injected Storage instance.

timeManager: TimeManager | None = ¶

Injected TimeManager instance.

validator: Validator = ¶

Injected Validator instance.

sortDiscoveryResources = ¶

Sort the discovered resources.

def _checkActiveCSESchedule(self): ¶

Check if the CSE is currently active according to its schedule.

Raises
`TARGET_NOT_REACHABLE`	In case the CSE is not active.

def _checkHybridID(self, request: CSERequest, id: str) -> tuple[str, str]: ¶

Return a corrected id and srn in case this is a hybrid ID.

Parameters
request:`CSERequest`	A request object that provides id and srn. srn might be None.
id:`str`	An ID which might be None. If it is not None, then it will be taken to generate the srn.

Returns
`tuple[str, str]`	Tuple of srn and id

def _childResourceTree(self, resources: list[Resource], targetResource: Resource | JSON): ¶

Retrieve child resources of a resource and add them to a new target resource instance as "children"

Parameters
resources:`list[Resource]`	A list of resources to retrieve the child resources from.
targetResource:`Resource \| JSON`	The target resource to add the child resources to.

def _discoverResources(self, rootResource: Resource, originator: str, level: int, fo: int, allLen: int, dcrs: list[Resource] | None = None, filterCriteria: FilterCriteria | None = None, permission: Permission | None = Permission.DISCOVERY) -> list[Resource]: ¶

Discover resources recursively. This is a helper function for discoverResources().

Parameters
rootResource:`Resource`	The root resource for discovery.
originator:`str`	The originator of the request.
level:`int`	The level of discovery.
fo:`int`	The filter operation.
allLen:`int`	The length of all filter criteria.
dcrs:`list[Resource] \| None`	The direct child resources of the root resource.
filterCriteria:`FilterCriteria \| None`	The filter criteria.
permission:`Permission \| None`	The permission to use.

Returns
`list[Resource]`	A list of discovered resources.

def _getFanoutPointResource(self, id: str) -> Resource | None: ¶

Check whether the target resource contains a fanoutPoint along its path is a fanoutPoint.

Parameters
id:`str`	the target's resource ID.

Returns
`Resource \| None`	Return either the virtual fanoutPoint resource, or None in case of an error.

def _getNotificationTargetSelfReferenceResource(self, id: str) -> NTSR | None: ¶

Check whether the target is a notificationTargetSelfReference virtual resource and return it.

Parameters
id:`str`	Target resource ID

Returns
`NTSR \| None`	Return either the virtual resource, or None in case of an error.

def _getPollingChannelURIResource(self, id: str) -> PCH_PCU | None: ¶

Check whether the target is a PollingChannelURI resource and return it.

Parameters
id:`str`	Target resource ID

Returns
`PCH_PCU \| None`	Return either the virtual PollingChannelURI resource or None.

def _getVirtualResource(self, id: str, rn: str | tuple[str, ...]) -> Resource | None: ¶

Check whether the target is a virtual resource and return it.

Parameters
id:`str`	Target resource ID
rn:`str \| tuple[str, ...]`	The resource name to check for. Can be a tuple of names. Must begin with a slash.

Returns
`Resource \| None`	Return either the virtual resource or None.

def _latestOldestResource(self, id: str) -> Resource | None: ¶

Check whether the target is a latest or oldest virtual resource and return it.

Parameters
id:`str`	Target resource ID

Returns
`Resource \| None`	Return either the virtual resource, or None in case of an error.

def _matchResource(self, r: Resource, fo: int, allLen: int, filterCriteria: FilterCriteria) -> bool: ¶

Match a filter to a resource.

def _resourcesToURIList(self, resources: list[Resource], drt: int) -> JSON: ¶

Create a m2m:uril structure from a list of resources.

def _resourceTreeReferences(self, resources: list[Resource], targetResource: Resource | JSON, drt: DesiredIdentifierResultType | None = DesiredIdentifierResultType.structured, tp: str | None = 'm2m:rrl') -> Resource | JSON: ¶

Retrieve child resource references of a resource and add them to a new target resource instance as "children"

Parameters
resources:`list[Resource]`	A list of resources to retrieve the child resource references from.
targetResource:`Resource \| JSON`	The target resource to add the child resource references to.
drt:`DesiredIdentifierResultType \| None`	Either structured or unstructured. Defaults to structured.
tp:`str \| None`	The type of the target resource. Defaults to 'm2m:rrl'.

Returns
`Resource \| JSON`	The target resource with the added child resource references.