Hemi JavaScript Framework
Hemi.data.io
Description
The Data IO service is used to broker data requests with configured data providers. The built-in interchange format is loosely modelled on the Account Manager 4 Data and Group object model, but the implementation is open for any object type.
Class Index
- static Hemi.data.io.DataIOProvider: This static class describes the interface an object must expose to provide data via the Data IO Service. A provider must be registered with the ObjectRegistry. The addServiceAPI method may be used to instrument this API for quick access to the service.
- static Hemi.data.io.service: Static implementation of the hemi.app.module.serviceImpl class.
- Hemi.data.io.serviceImpl: The Data IO service provides a bus to registered Data Providers. IORequest and IOSubject objects are used to convey a description of the request to the providers. Each provider may then determine whether and when to handled the request, and return results as an IOResponse.
static Hemi.data.io.DataIOProvider
version 3.1.9
This static class describes the interface an object must expose to provide data via the Data IO Service. A provider must be registered with the ObjectRegistry. The addServiceAPI method may be used to instrument this API for quick access to the service.
Index
Method Index
- public handle_io_open_request: A notification that a request has been opened.
- public handle_io_register: A notification that the provider was registered with the service.
- public handle_io_request: A notification that a request should be processed.
- public handle_io_unregister: A notification that the provider is being unregistered.
- public handle_proxy_xml: When registered as a protocol proxy, matching URI requests made from the context of the registered bus are diverted to this provider. The provider implements the handle_proxy_xml method to compose a Data IO Request based on the URI pattern. NOTE: Only one provider may register for a particular protocol, regardless of bus type.
- virtual implement: Registers a specific implementation. The order of the invocation is: requestCatalog{Action}, requestAction{Action}. This method is injected onto a provider after registration.
- virtual requestTypeAction: The virtual method is invoked based on the combination of the implements method.
Methods
handle_io_open_request
A notification that a request has been opened.
Syntax
void handle_io_open_request(
ioService, vSubj, ioRequest, ioResponse
)
Parameters
- ioService as DataIOService : The service that is unregistering the provider.
- vSubj as IOSubject : Subject of the requestor (E.G.: The authenticated user, anonymous user, etc).
- ioRequest as IORequest : The request that is being opened.
- ioResponse as IOResponse : The response to the request.
handle_io_register
A notification that the provider was registered with the service.
Syntax
void handle_io_register(
ioService
)
Parameters
- ioService as DataIOService : The service that registered the provider.
handle_io_request
A notification that a request should be processed.
Syntax
bComplete = handle_io_request(
ioService, vSubj, IORequest, ioResponse
)
Parameters
- ioService as DataIOService : The service that is unregistering the provider.
- vSubj as IOSubject : Subject of the requestor (E.G.: The authenticated user, anonymous user, etc).
- IORequest as IORequest : The request that is being opened.
- ioResponse as IOResponse : The response to the request.
Returns
bComplete as boolean: Bit indicating that the request response was completed.
handle_io_unregister
A notification that the provider is being unregistered.
Syntax
void handle_io_unregister(
ioService
)
Parameters
- ioService as DataIOService : The service that is unregistering the provider.
handle_proxy_xml
When registered as a protocol proxy, matching URI requests made from the context of the registered bus are diverted to this provider. The provider implements the handle_proxy_xml method to compose a Data IO Request based on the URI pattern. NOTE: Only one provider may register for a particular protocol, regardless of bus type.
Syntax
oRequest = handle_proxy_xml(
sPath, sId, bPost, vData, c, t, iBusType
)
Parameters
- sPath as String : The URI to an XML/Text/JSON Resource decorated with the proxy protocol.
- sId as String : Identifier associated with the request.
- bPost as bit : Bit indicating wether the request should be made via HTTP POST.
- vData as variant : Data to be included as the POST payload, such as an XMLDocument, text, or JSON structure.
- c as boolean (optional): Bit indicating whether the response should be cached.
- t as int (optional): Int indicating whether the request and response as text (1) or JSON (2) instead of XML (0).
- iBusType as int : The bus type the proxy service is currently operating in.
Returns
oRequest as DataIORequest: Returns a Data IO Request based on the supplied input.
implement
Registers a specific implementation. The order of the invocation is: requestCatalog{Action}, requestAction{Action}. This method is injected onto a provider after registration. Method is virtual and can be overridden.
Syntax
void implement(
sContext, sAction
)
Parameters
- sContext as String : The context of the implementation.
- sAction as String : The action of the implementation.
requestTypeAction
The virtual method is invoked based on the combination of the implements method. Method is virtual and can be overridden.
Syntax
bHandled = requestTypeAction(
oService, oSubject, oRequest, oResponse
)
Parameters
- oService as IOService : The Data IO service raising the request.
- oSubject as IOSubject : Subject of the requestor (E.G.: The authenticated user, anonymous user, etc).
- oRequest as IORequest : Parameters and filters of the request.
- oResponse as IOResponse : Data, status, and policies of the response.
Returns
bHandled as bit: Bit indicating the request was handled.
static Hemi.data.io.service
version 3.1.9
Static implementation of the hemi.app.module.serviceImpl class.
Hemi.data.io.serviceImpl
version 3.1.9
The Data IO service provides a bus to registered Data Providers. IORequest and IOSubject objects are used to convey a description of the request to the providers. Each provider may then determine whether and when to handled the request, and return results as an IOResponse.
Index
Object Index
- public Data: An object representing variable data.
- public Group: An object representing a group.
- public IOInstruction: Instructions relevent to the request.
- public IORequest: An object representing the subject of a request. This object is determined and set by the framework context. The parameters are modeled after the Core Web and Account ManagerCore Handler request processor.
- public IOResponse: An object representing the response to a request.
- public IOSubject: An object representing the subject of a request. This object is determined and set by the framework context.
- public Policy: Authorization policy affecting a particular object.
Method Index
- public arrayToData: Returns an array of data objects.
- public arrayToGroup: Returns an array of group objects.
- public continueRequest (internal): For asynchronous requests, continues processing the request transaction. The instance invoking this method may indicate that it completed processing its portion of the request, and therefore it should not receive a subsequent transaction processing callback.
- public createRequest (internal): Constructs a request object from the specified parameters, opens a new request transaction, and returns a new request object, registered with the io service, prepared with a response, and ready for use.
- virtual endRequest (internal): Specified for, and invoked as, the transaction packet handler for transactions opened for requests.
- public getBusName: Returns the name of the specified bus type.
- public getBusType: Returns the enumeration of bus types.
- public getList: Opens a catalog request, where the requestName is 'catalog',
- public getSubject: Returns the current IOSubject. This is assumed to be updated by any session handling mechanism (E.G.: Refer component.session.xml for implementation when used with Core Web 4 project).
- virtual handle_io_response: A notification that a response was created for a pending request.
- public isRegistered: Determines whether an object is registered as a provider.
- public mapSession (internal): Maps the Core Session component data to the DataIO subject.
- public newData: Returns a new data object.
- public newGroup: Returns a new group object.
- public newIOInstruction: Returns a new request object.
- public newIORequest (internal): Returns a new request object.
- public newIOResponse (internal): Returns a new response object.
- public newPolicy: Returns a new policy object.
- public openRequest (internal): Opens a new request transaction, and returns a new request object, registered with the io service, prepared with a response, and ready for use.
- public register: Registers a Data IO Provider.
- public unregister: Unregisteres a provider from the Data IO service.
- virtual updateSubject: Notifies subscribers to onupdatesubject message that the subject was updated.
Message Index
- public onupdatesubject: Message published to all subscribers when the default subject for the service has been updated.
Objects
Data
An object representing variable data.
Properties
- provider as String: The provider of the data.
- path as String: The path to the data.
- value as String: Value of the data.
- hash as String: Hash of the data value.
- name as String: Name of the data.
- type as String: Type of the data value.
- mimeType as String: Content type of the data value.
- id as String: Unique identifier.
- createdDate as Date: Date/time when the data was created.
- modifiedDate as Date: Date/time when the data was last modified.
- size as int: Size of the data
- detailsOnly as boolean: Bit indicating whether the data value is included. For data lists, this is usually false.
- postData as boolean: Bit indicating whether the data value represents a post payload.
- group as String: Group identifier. This may be used to differentiate the data relative to other data, such as a directory.
- description as String: Description of the data.
- namespace as String: Namespace. This may be used to distinguish where the data originates and/or where and how it should be persisted.
- bus as Enum<BusType>: The bus via which the data was transferred. Bus is a discriminator used to direct the flow of the request to a subject of IO Providers.
Group
An object representing a group.
Properties
- populated as boolean: Bit indicating whether child data and groups has been populated.
- provider as String: The provider of the group.
- parentId as String: The group parent id.
- name as String: Name of the group.
- path as String: Path of the group.
- type as String: Type of the group.
- id as String: Unique identifier.
- namespace as String: Namespace. This may be used to distinguish where the data originates and/or where and how it should be persisted.
- data as Array<Data>: List of data contained by the group.
- groups as Array<Group>: List of groups contained by the group.
- detailsOnly as boolean: Bit indicating whether the group pointers (such as children) are populated.
- bus as Enum<BusType>: The bus via which the group was transferred. Bus is a discriminator used to direct the flow of the request to a subject of IO Providers.
IOInstruction
Instructions relevent to the request.
Properties
- paginate as String: Bit indicating whether multiple results should be paginate by the
- recordCount as int: For paginated sets of data, the number of records requested for the set.
- startRecord as int: For paginated sets of data, the start index of the returned set of data from the total set.
- totalCount as int: For paginated sets of data, the total set of available data.
- paginate as boolean: Bit indicating the data set is paginated.
- orderBy as String: Instruction on how the response should be ordered.
- groupBy as String: Instruction on how the response should be grouped.
IORequest
An object representing the subject of a request. This object is determined and set by the framework context. The parameters are modeled after the Core Web and Account ManagerCore Handler request processor.
Properties
- requestApplication as String: The name of a preferred application to handle the requested action.
- requestAction as String: The requested action (eg: get, put, delete).
- async as String: The request may be made asynchronously, and the results returned via a handler callback.
- cache as String: The request results may be cached.
- requestName as String: Name of the request (eg: data name).
- requestId as String: UID of the request being made (eg: data id).
- requestCatalog as String: The catalog (or group) of the request being made (eg: Home group). This may be used to differentiate the data relative to other data, such as a directory.
- id as String: UID to track this IORequest.
- detailsOnly as boolean: Bit indicating whether returned data should include all information, or only meta information.
- requestContext as String: Context is used to distinguish where the data request originated, and where it may be delivered.
- namespace as String: Namespace. This may be used to distinguish where the data originates and/or where and how it should be persisted.
- eBus as Enum<BusType>: Bus is a discriminator used to direct the flow of the request to a subject of IO Providers.
- requestData as Array<Variant>: List of data accompanying the request.
- serviceId as String: The registered identifier of the service for which the request was created.
- providerRequested as Hash: Hash of provider identifiers to which the request was submitted.
- transactionId as String: The transaction packet identifier.
- transactionName as String: The transaction packet name.
- responseId as String: The id of the IOResponse created for this request. (IOResponse.id property, not IOResponse.responseId).
- is_open as boolean: Bit indicating that the request is still being processed.
- instruction as IOInstruction: A set of instructions for how a request for two or more records should be handled.
- mimeType as String: Expected content type of the response.
IOResponse
An object representing the response to a request.
Properties
- authenticationRequired as boolean: One or more providers indicated invalid authentication.
- id as String: UID to track this IOResponse.
- responseId as String: UID of the response (eg: data_id).
- responsePath as String: Path of the response.
- status as String: Response status.
- message as String: Response messages, if any.
- requestId as String: The id of the IORequest submitted and instigating this response. (IORequest.id property, not IORequest.requestId).
- serviceId as String: The registered identifier of the service for which the response was created.
- responseData as Array<Variant>: List of data accompanying the response.
- namespace as String: Namespace. This may be used to distinguish where the data originates and/or where and how it should be persisted.
- eBus as Enum<BusType>: Bus is a discriminator used to direct the flow of the request to a subject of IO Providers.
- providerResponded as Hash: Hash of providers which responded.
- responseHandler as function: Handler to be invoked for asynchronous requests.
Methods
- void writeData(
o, p, r, b)
Adds the specified data object to the response.
- void writeDataArray(
a, p, r, b)
Adds the specified data objects to the response.
- void writeGroup(
o, p, r, b)
Adds the specified group object to the response.
- void writeGroupArray(
a, p, r, b)
Adds the specified group objects to the response.
IOSubject
An object representing the subject of a request. This object is determined and set by the framework context.
Properties
- name as String: Name of the subject (eg: user name).
- id as String: UID of the subject (eg: user id).
- isAuthenticated as boolean: Bit indicating whether or not the subject is known to be authenticated.
Policy
Authorization policy affecting a particular object.
Properties
- subjectId as String: The id of the object that the policy affects.
- subjectType as String: The type of subject.
- statement as String: A plain text statement of the policy.
- read as boolean: Bit indicating whether the subjecrt is able to read the object.
- write as boolean: Bit indicating whether the subjecrt is able to write (or add-to) the object.
- change as boolean: Bit indicating whether the subjecrt is able to change the object.
- del as boolean: Bit indicating whether the subjecrt is able to delete the object.
Methods
arrayToData
Returns an array of data objects.
Syntax
aData = arrayToData(
aArray, oPolicy
)
Parameters
- aArray as Array<String> : An array of data
- oPolicy as Policy : Default data policy.
Returns
aData as Array<Data>: An array of data objects.
arrayToGroup
Returns an array of group objects.
Syntax
aGroups = arrayToGroup(
aArray, oPolicy, sParentPath
)
Parameters
- aArray as Array<String> : An array of group names
- oPolicy as Policy (optional): Default group policy.
- sParentPath as String (optional): Parent path to the group.
Returns
aGroups as Array<Group>: An array of group objects.
continueRequest
For asynchronous requests, continues processing the request transaction. The instance invoking this method may indicate that it completed processing its portion of the request, and therefore it should not receive a subsequent transaction processing callback.
Syntax
void continueRequest(
ioRequest, oProvider, bComplete
)
Parameters
- ioRequest as variount : Request object or request identifier.
- oProvider as ProviderObject (optional): The provider object instigating the request to continue processing.
- bComplete as boolean : Bit indicating that the provider completed processing the request and that the underlying transaction may be marked as complete.
createRequest
Constructs a request object from the specified parameters, opens a new request transaction, and returns a new request object, registered with the io service, prepared with a response, and ready for use.
Syntax
oReq = createRequest(
oSubject, eBus, sApplication, sContext, sCatalog, sAction, sId, sName, bDetailsOnly, bAsync, bCache, oInstruction, fHandler
)
Parameters
- oSubject as IOSubject : The subject making the request.
- eBus as Enum<BusType> : The request bus.
- sApplication as String : The request application.
- sContext as String : The context of the request.
- sCatalog as String : The name of the request catalog.
- sAction as String : The requested action.
- sId as String : The requested id.
- sName as String : The name of the request.
- bDetailsOnly as boolean : The request is for meta information.
- bAsync as boolean : The request is asynchronous.
- bCache as boolean : The request may be cached.
- oInstruction as IOInstruction : A set of instructions for how a request for two or more records should be handled.
- fHandler as function (optional): Function pointer to be invoked with the service and response.
Returns
oReq as IORequest: A request object.
endRequest
Specified for, and invoked as, the transaction packet handler for transactions opened for requests. Method is virtual and can be overridden.
Syntax
void endRequest(
oService, oPacket
)
Parameters
- oService as TransactionService : The transaction service handling the request.
- oPacket as TransactionPacket : The packet representing the transaction.
getBusName
Returns the name of the specified bus type.
Syntax
sBusName = getBusName(
iBus
)
Parameters
Returns
sBusName as String: The name of the specified of bus type.
getBusType
Returns the enumeration of bus types.
Syntax
eBus = getBusType(
)
Returns
eBus as Enum<BusType>: The enumeration of bus types.
getList
Opens a catalog request, where the requestName is 'catalog',
Syntax
oResp = getList(
eBus, sApplication, sContext, sCatalog, sRequest, bAsync, fHandler
)
Parameters
- eBus as Enum<BusType> : The request bus.
- sApplication as String : The application to handle the request.
- sContext as String : The context of the request.
- sCatalog as String : The group catalog. Reserved values are: directory, data
- sRequest as String (optional): The request, or description, of the catalog. Reserved values are: list, listFull.
- bAsync as boolean (optional): Bit indicating whether the request should be made asynchronously.
- fHandler as function (optional): Function pointer to be invoked with the service and response.
Returns
oResp as IOResponse: The response object created for the request.
getSubject
Returns the current IOSubject. This is assumed to be updated by any session handling mechanism (E.G.: Refer component.session.xml for implementation when used with Core Web 4 project).
Syntax
oSub = getSubject(
)
Returns
oSub as IOSubject: The current IOSubject.
handle_io_response
A notification that a response was created for a pending request. Method is virtual and can be overridden.
Syntax
void handle_io_response(
ioService, vSubj, ioRequest, ioResponse
)
Parameters
- ioService as DataIOService : The service that is unregistering the provider.
- vSubj as IOSubject : Subject of the requestor (E.G.: The authenticated user, anonymous user, etc).
- ioRequest as IORequest : The request that is being opened.
- ioResponse as IOResponse : The response to the request.
isRegistered
Determines whether an object is registered as a provider.
Syntax
bRegistered = isRegistered(
oObject
)
Parameters
- oObject as FrameworkObject : Hemi FrameworkObject.
Returns
bRegistered as bit: Bit indicating whether the provider is registered.
mapSession
Maps the Core Session component data to the DataIO subject.
Syntax
void mapSession(
oSession
)
Parameters
- oSession as SessionComponent : The Session Component used by CoreWeb.
newData
Returns a new data object.
Syntax
oData = newData(
)
Returns
oData as Data: A new data object.
newGroup
Returns a new group object.
Syntax
alist = newGroup(
)
Returns
alist as Data: A new group object.
newIOInstruction
Returns a new request object.
Syntax
oInst = newIOInstruction(
bPaginate, iStartRecord, iRecordCount, sOrder, sGroup
)
Parameters
- bPaginate as boolean : The requested results should be paginated.
- iStartRecord as int : For paginated results, the record to begin with.
- iRecordCount as int : For paginated results, the maximum number of records to return.
- sOrder as String : Record order instruction.
- sGroup as String : Record group instruction.
Returns
oInst as IOInstruction: A new set of request instructions.
newIORequest
Returns a new request object.
Syntax
oReq = newIORequest(
eBus, sApplication, sContext, sCatalog, sAction, sId, sName, bDetailsOnly, bAsync, bCache, oInstruction
)
Parameters
- eBus as Enum<BusType> : The request bus.
- sApplication as String : The request application.
- sContext as String : The context of the request.
- sCatalog as String : The name of the request catalog.
- sAction as String : The requested action.
- sId as String : The requested id.
- sName as String : The name of the request.
- bDetailsOnly as boolean : The request is for meta information.
- bAsync as boolean : The request is asynchronous.
- bCache as boolean : The request may be cached.
- oInstruction as IOInstruction : A set of instructions for how a request for two or more records should be handled.
Returns
oReq as IORequest: A new request object.
newIOResponse
Returns a new response object.
Syntax
oReq = newIOResponse(
vReq, fHandler
)
Parameters
- vReq as IORequest : The request object for which to create the response.
- fHandler as function (optional): Function pointer to be invoked with the service and response for asynchronous requests.
Returns
oReq as IOResponse: A new response object.
newPolicy
Returns a new policy object.
Syntax
oPolicy = newPolicy(
)
Returns
oPolicy as Policy: A new policy object.
openRequest
Opens a new request transaction, and returns a new request object, registered with the io service, prepared with a response, and ready for use.
Syntax
oReq = openRequest(
oSubject, IORequest, fHandler
)
Parameters
- oSubject as IOSubject : The subject making the request.
- IORequest as function : A request object.
- fHandler as function (optional): Function pointer to be invoked with the service and response.
Returns
oReq as IORequest: A request object.
register
Registers a Data IO Provider.
Syntax
bRegistered = register(
oProvider, sBusType, sProviderName, sProtocolProxy
)
Parameters
- oProvider as ProviderObject : Hemi FrameworkObject that supports the Provider API.
- sBusType as String (optional): The type of bus the provider will use. Fixed types are: local, offline, online, any.
- sProviderName as String (optional): A friendly name for refering to the provider.
- sProtocolProxy as String (optional): A custom protocol for directing URI requests through the provider.
Returns
bRegistered as bit: Bit indicating whether the provider was registered.
unregister
Unregisteres a provider from the Data IO service.
Syntax
bRegistered = unregister(
oProvider, bPointer
)
Parameters
- oProvider as ProviderObject : Hemi FrameworkObject that supports the Provider API.
- bPointer as boolean : Bit indicating the provider is an internal marker.
Returns
bRegistered as bit: Bit indicating whether the provider was unregistered.
updateSubject
Notifies subscribers to onupdatesubject message that the subject was updated. Method is virtual and can be overridden.
Syntax
void updateSubject(
)
Messages
onupdatesubject
Message published to all subscribers when the default subject for the service has been updated.
Syntax
// User-specified script to subscribe to message
org.cote.js.message.MessageService.subscribe("onupdatesubject",_handle_message);
// Internal: how the message is published to subscribers
org.cote.js.message.MessageService.publish("onupdatesubject"
, o
);
// User-specified script to handle the message subscription
function _handle_message("onupdatesubject"
, o
){
// message handler code
}
Parameters
- o as DataIOService : The service for which the subject was updated.
[ Hemi JavaScript Framework - Stephen W. Cote, 2002 - 2011. ]