Proposed Revised DCCI Model

From UWA
Jump to: navigation, search


Salient features:

  1. Through contextInterface, obtain either an interface to the context model (root node) or to provider interface
  2. Fire event to providers by consumers and vice versa
  3. Root node is used for getting and setting model data
  4. Property related data is obtained directly from the property
  5. No hierarchical representation model but dependencies can be modelled
  6. Event handlers are added directly at the properties of interest
  7. Seperate provider node interfaces for abstract and non-abstract nodes
  8. Independent of any event scheme or propagation type


The StringList interface (borrowed from DOM Core specification)

Interface StringList{
	String Item(in unsigned long index);
	Readonly attribute unsigned long length;
}


1. Interface Node* contextInterface(string domain, string interfaceType, optional string signedCertificateParams);

The contextInterface may be a constructor interface that provides an interface to the context model that is of the type indicated by interfaceType parameter. The interfaceType parameter can be either “root” or “provider” string. In the case of “root”, the method returns a RootNode interface and in the case of “provider”, it returns a providerNode interface. Thus the return type Node can either be a RootNode or providerNode.


2. RootNode Interfaces

Interface RootNode{
 Interface* contextInterface(string domain, optional string signedCertificateParams);
 Interface struct ModelInfo StringList getModelData(String QueryParameter);
 Interface String setModelData(string setParameter, stringList setValue);
 Interface fireEvent(struct eventStruct* event, optional PropertyNode);
 Interface propertyList* getPropertyList(in propertyFilterList* filter);
 Interface valueList* getLocalHistory(optional propertyFilterList* propertyList, optional propertyLocalStoreID,  unsigned int milliseconds);
 Optional Interface requestSecurityMode(appCredential* credentials, string securityMode); and
 Optional Interface String synchronize(propertyList properties, String remoteURI, String SynchronizeMmode, Optional String synchType).  
}

In case of RootNode, each application may be enabled to create a new instance and the underlying model may provide the interface that is based on the security settings for that domain. The method returns the RootNode interface to the calling application. This interface can then be used to call all the root node interfaces. The contextInterface may be called as part of the document or window object of the browser and may be implementation specific. For example, an JavaScript application may get the RootNode interface by making the call rootNode = window.contextInterface(“application”, credentials, “root”);


2.1 Interface struct modelInfo getModelData();

The interface getModelData is called to get information about the context model. Calling this method returns a ModelInfo structure that lists all the information about the current model.

Struct modelInfo{
	String Version;
	String OEM;
	String EventScheme;
	String ContextStructure;
	String Ontology;
	String Mode;
	StringList SupportedEventSchemes;
	StringList SupportedStructures;
}

The supported fields inside the ModelInfo structure QueryParameters may include Version (e.g., the current version number), OEM (e.g., the manufacturer name), NameSpace (e.g., the namespace to which the interface conforms), EventScheme (e.g., providing the current event scheme employed), ContextStructure (the current context structure e.g., providing the current context representation structure employed such as “tree”, “backbone”, or “mixed”), Ontology (e.g., providing the current ontology supported by the implementation), Mode (e.g., local device context only or “smart” mode with tree composition), SupportedEventSchemes (e.g., providing a list of event schemes supported by the implementation), SupportedStructures (e.g., providing the list of context structures supported by the implementation). If there are more than one structure is supported, it may be possible for the application to request a particular structural representation of the model for the current session. The model can then re-organize the property nodes in accordance with that structure. This may also affect the particular event scheme employed.

2.2 Interface String setModelData(string setParameter, stringList setValue);

The setParameter may indicate what property has to be set for this model and current session. The return value may indicate whether the setting has been a success, a failure, is not supported and is not authorized. The setValue may indicate the value that has to be set for this session. The setModelData is an optional interface that can return a not supported string for all parameters. Some examples of setParameters are provided below including:

  • EventScheme: set an event scheme that is different from default
  • ContextStructure: set a context structure that is different from default
  • Mode: change mode from local to smart or vice versa
  • Ontology: support a new ontology other than the default
  • Synchronize: synchronize properties with an external repository in which parameters to pass may include the uniform resource identifier (URI) of a remote repository, property list of properties to be synchronized
  • StorePropertyValue: store a particular property value that changed during the session. Return value is a string that is used as an identifier for later retrieval. In some cases, this value may only be possible in platforms where local storage is supported. Otherwise, not supported may be returned.


2.3 Interface fireEvent(in struct eventStruct* event, in optional PropertyNode);

The fireEvent interface is used by consumer properties to fire an event into the model for notification on properties. The event handler is also provided that must be called in case the parameters mentioned in eventStruct are statisfied. PropertyNode is optional. If propertyNode is present, then the corresponding property identified may be targeted. Otherwise, this flows either to the whole model or in a direction determined by a combination of context model structure and event scheme.

2.4 Interface propertyList* getPropertyList(in propertyFilterList* filter);

The propertyList interface may be employed to obtain a list of properties within the model that satisfies filter criterion.

Interface propertyList{
	Property* Item(in unsigned long index);
	Readonly attribute unsigned long length ;
}

Struct propertyFilterList{
	String propertyName;
 	String propertyNameSpace;
 	String propertyAspect; //denotes type of property example printer, default is “general”
 	String valueType;
 	String metadataType;
 	String propertyProviderName;
 	String propertyProviderNameSpace;
 	String propertyProviderURI;
 	String propertyInterfaceExtensionType;
 	String propertyInterfaceExtensionURI;
 	String propertyLocalStoreID;
 	String propertyVersion;
 	Enumerated String source; //Local or Remote property
 	String sourceURI; //actual location of current property if remote
 	String hierarchyLevel  ;
}

The propertyFilterList structure may provide a list of the filter criterion (all fields are optional) for one property. The filter may be used to determine whether a property is present in the context model. Since the context model does not assume exclusivity of this property, there can be multiple instances present and the propertyList may hold all instances of occurrence of this property.


2.5 Interface valueList* getLocalHistory(optional propertyFilterList* propertyList, optional StringList propertyLocalStoreID, unsigned int milliseconds);

The valueList interface may enable retrieval of a local history of a property for the past N milliseconds from a local data store. The propertyLocalStoreID is an optional list of property local store id (if supported) that helps to identify particular properties. This is useful where they may be duplicates of properties within a storage service.

2.6 Optional Interface requestSecurityMode(appCredential* credentials, string securityMode);

This interface requests the model that a particular security model may be granted for the calling application. The application submits its credentials and the requested security mode as parameters to the method call.

2.7 Optional Interface String synchronize(propertyList properties, String remoteURI, String SynchronizeMode, Optional String synchType);

The String synchronize interface may be used to synchronize certain properties with a remote server, if supported. The SynchronizeMode parameter of this interface may denote how the synchronization happens (e.g., whether from local device only to server, from server to local device only or both ways (e.g., synchronization through timestamp conforming to (NTP) network time protocol)). The optional synchType parameter may provide a suggestion as to what protocol to employ for synchronization. In some cases, a default protocol may be provided, but others may be requested to override the default synchronization protocol.

3. Property Node Interfaces

The property node interfaces are given below:

Interface Property{
 	Interface valueList* getLocalHistory(optional date startDate, unsigned int milliseconds);
 	Interface propertyInfo getPropertyInfo();
 	Interface metadata getMetaData();
 	Interface valueStruct getValue();
 	Interface eventStruct* getAppEventList();
 	Interface fireEvent(struct eventStruct* event);
 	Interface addEventHandler(struct eventStruct event, function eventHandler);
 	Interface* queryInterface(string interfaceName);
 	Interface propertyList getDependants(); 
}


Interface descriptions for property node

3.1 Interface valueList* getLocalHistory(optional date startDate, unsigned int milliseconds);

Interface valueList{
	Unsigned int length;
	Optional unsigned int timeInterval;
	Optional Date insertionDate;
	valueStruct getValue(optional unsigned int long index, optional time);
}


The getLocalHistory method is used to get a time-based value list of property values over a period of time. This may be obtained either from the local storage module or obtained from a server-based storage depending on the implementation.

3.2 Interface propertyInfo getPropertyInfo();

The propertyInfo interface may be used to provide information structure corresponding to a particular property.

Struct propertyInfo{
 	String propertyName;
 	String propertyNameSpace;
 	String propertyAspect; //denotes type of property example printer, default is “general”. See http://www.w3.org/TR/DDR-Simple-API/
 	String valueType;
 	String metadataType;
 	String propertyProviderName;
 	String propertyProviderNameSpace;
 	String propertyProviderURI;
 	String propertyInterfaceExtensionType;
 	String propertyInterfaceExtensionURI;
 	String propertyLocalStoreID;
 	String propertyVersion;
 	Unsigned int propertyUpdateTimeStamp;
 	Unsigned int propertyAddedTimeStamp;
 	Enumerated String source; //Local or Remote property
 	Optional String sourceURI; //actual location of current property if remote
}

3.3 Interface metadata getMetaData();

The metadata interface may provide the metadata structure for the corresponding property. The fields in the structure may be property specific and may be defined in a separate document such as the ontology.

3.4 Interface valueStruct getValue();

The method getValue returns the current value of the property. The valueStruct getValue interface may be NULL if no value is present.

3.5 Interface eventStruct* getAppEventList();

The getAppEventList interface may enable access to a list of supported events that can be fired by a consumer of a corresponding property. This returns an eventStruct that lists the events supported by this property. All the properties support a basic set of events that may be defined by a separate authority. The events may be property change event, property addition event, property delete event, value change event etc. In addition, property specific events may also be supported that are listed through the eventStruct structure.

3.6 Interface fireEvent(in struct eventStruct event);

The fireEvent interface may be fired by a consumer application on a corresponding property. The fireEvent is used by the consumer to notify the property of any application state change or request some adapted or customized service dynamically.

3.7 Interface addEventHandler(struct eventStruct event, function eventHandler);

The interface addEventHandler is used by the consumer application to attach an event handler at that particular property to handle any particular or set of events. The event struct may be a super set of event parameters that may be used in filtering events, firing events from provider properties to consumer applications as well as requests for service from consumer applications to the model. The eventStruct may include multiples of eventName, eventType and optional eventPhase combinations.

3.8

Struct eventStruct{
 String eventName;
 String eventType; //defines the type of event, for example, topology change event, value change event, node addition, node removal, etc.
 Optional string eventPhase; //defines for what event phase the interface is used  (optional and dependent on the event scheme).
 String list event parameters; //provides a list of parameters to be determined.
}

3.9 Interface* queryInterface(string interfaceName);

The property can be queried for a particular interface, usually an extension to a standard interface. If supported, the interface (e.g., a function pointer) is returned. The calling application can then use the interface and its associated parameters.

3.10 Interface propertyList getDependants();

The getDependants interface returns a list of properties that hold a first-level relation to this property. If a hierarchical relation exists between a property and other properties, the properties that fall in the immediate level below the current property is returned as a propertyList.


Getting provider node interface


Optional providerNode* getProviderNodeInterface();

This optional method returns the providerNode interface. The method can be called either as part of the window object or document object depending on the implementation type. Another way to get the providerNode interface is to call contextInterface method with “provider” parameter as explained earlier.

4. Provider Node Interfaces

Interface providerNode{
 Interface String UniqueID getModelEntry(struct providerParameters, String propertyAspect, propertyInfo property);
 Interface String Status requestSecurityClass(provCredentials* credentials, string securityClass, in string UniqueID);
 Interface String registerExtensionCallBack(function* callback, in string UniqueID);
 Interface String Status setInterfaceExtensions(in struct extensionList extension, in string UniqueID);
 Interface String Status registerSupportedEvents(eventStruct events, function* eventCallBack, Boolean acceptAll, in string UniqueID);
 Interface updateValue(struct valueStruct, in string UniqueID);
 Interface String status removeNode(in string UniqueID);
 Interface unsigned int queryApplicationUsage(in string UniqueID);
}

4.1 Interface String UniqueID getModelEntry(struct providerParameters, String propertyAspect, propertyInfo property);

The String UniqueID interface may sometimes be the first interface that is called. In this regard, the provider may submit its parameters to the framework and, if accepted, the framework may provide back a uniqueID for use during all future communications with the framework for a particular session. The PropertyAspect may define whether a property being added is considered to be a “direct” or “abstraction” node. Other propertyAspects may also be defined and added in the future. Direct nodes provide direct values from the provider whereas Abstract nodes (e.g., abstraction nodes) take values from other nodes based on some given formula. The use of a property "aspect" to refine the semantics of a property is borrowed from a similar concept introduced in the W3C DDR Simple API.

Direct Node Entry Interfaces (non-abstract nodes)

4.2.1 Interface String Status requestSecurityClass(provCredentials* credentials, string securityClass, in string UniqueID);

The interface above defines an interface used to request a particular security class for a corresponding provider.

4.2.2 Interface String registerExtensionCallBack(function* callback, in string UniqueID);

The method above defines an interface that may be called to register a function call-back that is called whenever an extension function to the property node is called. This is provided by the provider to the context model. The call-back may take in two parameters, the first of which may be the name of the application that called the function, and the second of which may be the string that denotes the function related string along with the parameter values. The manner by which the function name and parameters are interpreted may be up to the provider that provided the interface extension and the callback. After registering the callback, the provider may also call the SetInterfaceExtensions method to register the extension functions.

4.2.3 Interface String Status setInterfaceExtensions(in struct extensionList extension, in string UniqueID);

The interface above defines an interface that may be used by providers to set extensions to the standard list of property interfaces. The in parameter may be an extensionList structure that lists the function name, the parameter that each function takes, and the string that is to be returned when a function call is made.

Struct extensionList{

String extensionType; //provides an extension type that defines this extension, if any. 
String extensionClass; //provides a security class to which this interface belongs if supported by implementation.
Unsigned int length;
Struct ExtFunction function1;
Struct ExtFunction function2;
Struct ExtFunction function3;
......

};

Struct ExtFunction{
String extensionType; //provides an extension type to which this function conforms if any. If present, this takes precedence over that of the extensionList struct.
String extensionClass; //provides a security class to which this interface belongs if supported by implementation.
Unsigned int paramNos; //provides a number of parameters.
String name; //the extension function name
Type any parameter param1;
.....

String callBackString; //provides the callback string to use when calling the registered callback. 
The callback string is concatenated with the string versions of the parameter with each separated 
by an “&” sign and in order of how they appear in the corresponding struct. 
};

4.2.4 Interface String Status registerSupportedEvents(eventStruct events, function* eventCallBack, Boolean acceptAll, in string UniqueID);

The interface above defines an interface that may be employed to register a set of events that are supported by the corresponding property. The events can be fired by the consumer to provide information regarding consumer status, needed configurations, setting parameters (either through extension or event firing), etc. The eventCallBack method is called by the framework with the eventstruct when the consumer fires the event to that propertynode. The acceptAll parameter shows whether to accept all events that come to the corresponding node or to accept only those that were fired on the corresponding node.

4.3 Abstract provider node interfaces

The interfaces described immediately hereafter may only be provided if the node type is declared to be abstract node in some embodiments.

Interface providerNode{
 Interface propertyList* queryProperty(in propertyList, in string UniqueID);
 Interface valueStruct* getValue(in propertyList, in string UniqueID);
 Interface updateValue(struct valueStruct, in string UniqueID);
 Interface String status removeNode(in string UniqueID);
 Interface unsigned int queryApplicationUsage(in string UniqueID);
}

4.3.1 Interface propertyList* queryProperty(in propertyList, in string UniqueID);

The interface above defines an interface directing a query of the model for a list of properties that are supported and present. The return list provided responsive to this interface may have the list of properties that are present in the query within the model.

4.3.2 Interface valueStruct* getValue(in propertyList, in string UniqueID);

The interface above defines an interface that enables obtaining the value for properties mentioned in the property list.

4.4 Common interfaces to non-abstract and abstract provider nodes

4.4.1 Interface updateValue(struct valueStruct, in string UniqueID);

The updateValue method may be used to update its current value to the model.

4.4.2 Interface String status removeNode(in string UniqueID);

The interface above defines an interface that may be used to remove the node from the model and close the session.

4.4.3 Interface unsigned int queryApplicationUsage(in string UniqueID);

The interface above defines an interface that may be used to query how many applications are using the provider property.