# Presentation: 464122

## Service Data and Notification Interfaces in OGSI

- Keith R. Jackson
- Lawrence Berkeley National Laboratory
- krjackson@lbl.gov

## Standard way to expose a service instance’s state data.
No service data specific operations defined.
No getXXX() or setXXX() functions
GridService portType defines base operations for manipulating Service Data by name
A new child element of portType is defined: serviceData.

- No service data specific operations defined.
- No getXXX() or setXXX() functions
- GridService portType defines base operations for manipulating Service Data by name
- A new child element of portType is defined: serviceData.

- Service Data Elements

- <gwsdl:portType name="NCName"> *
- <wsdl:documentation .... /> ?
- <wsdl:operation name="NCName"> *
- ...
**<sd:serviceData name="NCName" ... /> ***
**<sd:staticServiceDataValues>?**
**<some element>***

## SDE Example

- <wsdl:definitions xmlns:tns=”xxx” targetNamespace=”xxx”>
- <gwsdl:portType name="exampleSDUse"> *
- <wsdl:operation name=...>
- ...
- <sd:serviceData name="sd1" type=”xsd:String”
- mutability=”static”/>
- <sd:serviceData name="sd2" type=”tns:SomeComplexType”/>
**...**
- <sd:staticServiceDataValues>
- <tns:sdl>initValue</tns:sd1>
- </sd:staticServiceDataValues>
- </gwsdl:portType>
- ...
- </wsdl:definitions>

## SDE Schema

- ...
- targetNamespace =
- “http://www.gridforum.org/namespaces/2003/serviceData”
- xmlns:sd =
- “http://www.gridforum.org/namespaces/2003/03/serviceData”
- ...
- <xsd:complexType name=“ClosedServiceDataElementType” mixed=”true”>
- <xsd:complexContent>
- <xsd:restriction base=”xsd:element”>
- <xsd:sequence>
- <xsd:element ref="xsd:annotation" minOccurs="0"/>
- </xsd:sequence>
- <xsd:attribute name="name" type="xsd:NCName"/>
- <xsd:attribute name="type" type="xsd:QName" />
- <xsd:attributeGroup ref="xsd:occurs" />

## SDE Schema (cont.)

- <-- minOccurs, maxOccurs -->
- <xsd:attribute name="nillable" type="xsd:boolean"
- use="optional" default="false" />
- </xsd:restiction>
- </xsd:complexContent>
- </xsd:complexType>
- <xsd:complexType name=”ServiceDataType” mixed=”true”>
- <xsd:complexContent>
- <xsd:extension base=”sd:ClosedServiceDataElementType”>
- <xsd:sequence>
- <xsd:any namespace="##other" minOccurs="0"
- maxOccurs="unbounded" />
- </xsd:sequence>
- <xsd:attribute name="mutability" default=”extendable”>

## SDE Schema (cont.)

- <xsd:simpleType>
- <xsd:restriction base="xsd:string">
- <xsd:enumeration value="static"/>
- <xsd:enumeration value="constant"/>
- <xsd:enumeration value="extendable"/>
- <xsd:enumeration value="mutable"/>
- </xsd:restriction>
- </xsd:simpleType>
- </xsd:attribute>
- <xsd:attribute name="modifiable" type=”xsd:boolean”
- default=”false”>
- <anyAttribute namespace="##other" processContents="lax"/>
- </xsd:extension>
- </xsd:complexContent>

## SDE Schema (cont.)

- </xsd:complexType>
- <element name=”serviceData” type=”sd:ServiceDataType”/>
- <xsd:complexType name=”ServiceDataValuesType”>
- <xsd:sequence>
- <xsd:any namespace="##any" minOccurs="0"
- maxOccurs="unbounded" />
- </xsd:sequence>
- </xsd:complexType>
- <element name=”serviceDataValues”
- type=”sd:ServiceDataValuesType”/>
- <element name=”staticServiceDataValues”
- type=”sd:ServiceDataValuesType”/>

## SDE Schema Elements

- maxOccurs = (nonNegativeInteger | unbounded) : default to 1
- This value indicates the maximum number of serviceData element values that can appear in the service instance’s serviceDataValues or the portType staticServiceDataValues.
- minOccurs = nonNegativeInteger : default to 1
- This value indicates the minimum number of serviceData element values that can appear in the service instance’s serviceDataValues or the portType staticServiceDataValues.
- If the value is 0, then the serviceData element is optional

## SDE Schema Elements (cont.)

- name = NCName and {target namespace}
- The name of the serviceData element must be unique amongst all sd:serviceData and xsd:element declarations in the target namespace of the wsdl:definitions element.
- The combination of the name of the serviceData element and the target namespace of the wsdl:definitions element’s targetNamespace attribute forms a QName, allowing a unique reference to this serviceData element.
- nillable = boolean : default to false
- Indicates whether the serviceData element can have a nil value (that is a value that has an attribute xsi:nil with value=“true”).
- For example a serviceData declaration
- <serviceDataElement name=”foo” type=”xsd:string” nillable=true” />
- can have a valid SDE value
- <foo xsi:nil=”true”/>

## SDE Schema Elements (cont.)

- type = QName
- Defines the XML schema type of the serviceData element value
- modifiable = “boolean” : default to false
- If true, it is legal for requestors to directly update the serviceData value through the setServiceData operation (see §9.2.2), subject to constraints on cardinality (minOccurs, maxOccurs) and mutability. If false, the serviceData element should be regarded as “read only” by the requestor, though its values may change as a result of other operations on the service’s interface.
- mutability = “static” | “constant” | “extendable” | “mutable” : default to extendable
- An indication of whether and how the values of a serviceData element can change.

## SDE Schema Elements (cont.)

- {any attributes with non-schema namespace}
- Open content on the attributes of serviceData declaration is allowed.
- Content
- annotation
- This element allows documentation elements to appear as children of a serviceData declaration
- Open content element model, meaning elements from any other namespace (besides XML Schema) may appear as child elements of the serviceData element.
- A serviceData element extends a restricted of xsd:element to allow open element content model,

## Grid Service PortType Example

- <wsdl:definitions ...
- <gwsdl:portType name=”GridService” ...>
- <wsdl:operation name= ...>
- ...
- <sd:serviceData name=”interface” type=”xsd:QName”
- minOccurs=”1” maxOccurs=”unbounded”
- mutability=”constant”/>
- <sd:serviceData name=”serviceDataName” type=”xsd:QName”
- minOccurs=”0” maxOccurs=”unbounded”
- mutability=”mutable” nillable=”false”/>
- <sd:serviceData name=”factoryHandle”
- type=”ogsi:HandleType”
- minOccurs=”1” maxOccurs=”1”
- mutability=”constant” nillable=”true”/>

## Grid Service PortType Example (cont.)

- <sd:serviceData name=”gridServiceHandle”
- type=”ogsi:HandleType”
- minOccurs=”0” maxOccurs=”unbounded”
- mutability=”extendable”/>
- <sd:serviceData name=”gridServiceReference”
- type=”ogsi:ReferenceType”
- minOccurs=”0” maxOccurs=”unbounded”
- mutability=”mutable”/>

## Grid Service PortType Example (cont.)

- <sd:serviceData name=”findServiceDataExtensibility”
- type=”ogsi:OperationExtensibilityType”
- minOccurs=”1” maxOccurs=”unbounded”
- mutability=”static”/>
- <sd:serviceData name=”terminationTime” type=”ogsi:terminationTime”
- minOccurs=”1” maxOccurs=”1”
- mutability=”mutable”/>
- <sd:serviceData name=”setServiceDataExtensibility”
- type=”ogsi:OperationExtensibilityType”
- minOccurs=”2” maxOccurs=”unbounded”
- mutability=”static” />
- ...

## findServiceData

**GridService :: findServiceData**
- Query the service data.
**Input**
- • *QueryExpression*: The query to be performed. This extensib le parameter MUST conform to an inputElement declaration denoted by one of the findServiceDataExtensibility SDE values. Note: The service infers what to do based on the tag of the root element of this argument.
**Output**
- • *Result*: The result of the query. The format of this result is dependent upon the QueryExpression.

## findServiceData (cont.)

**Fault(s)**
- • *ExtensibilityNotSupportedFault: *Indicates that the service cannot evaluate the
- QueryExpression because its type is not supported by this service.
- • *ExtensibilityTypeFault*: Indicates that the value passed as the QueryExpression violates
- that value’s type.
- • *TargetInvalidFault*: Indicates that one or more of the SDEs that the QueryExpression
- requires do not exist in this service.
- • *Fault*: Any other fault.

## setServiceData

**GridService :: setServiceData**
- This operation allows for the modification of a service data element’s values, if its service data declaration specifies modifiable=”true”. Changing a modifiable service data element implies changing the corresponding state in the underlying service instance. If no service data elements have a modifiable=”true” attribute then setServiceData is essentially disabled.
**Input**
- • *UpdateExpression*: The update to be performed. This extensible parameter MUST conform to an inputElement declaration denoted by one of the setServiceDataExtensibility SDE values. Note: The service infers what to do based on the tag of the root element of this argument

## setServiceData (cont.)

**Output**
- • *Result*: The result of the update. The format of this result is dependent upon the UpdateExpression.
**Fault(s)**
- • *ExtensibilityNotSupportedFault: *Indicates that the service cannot evaluate the UpdateExpression because its type is not supported by this service.
- • *ExtensibilityTypeFault*: Indicates that the value passed as the UpdateExpression violates that value’s type.
- • *CardinalityViolationFault: *Indicates that operation requested would violate the “minOccurs” and/or “maxOccurs” attributes of the service’s SDE(s).
- • *MutabilityViolationFault: *Indicates that the UpdateExpression was not consistent with the “mutability” attribute of the service’s SDE(s).
- • *ModifiabilityViolationFault: *Indicates that the UpdateExpression was not consistent with the “modifiable” attribute of the services’s SDE(s).

## setServiceData (cont.)

- • *TypeViolationFault: *Indicates that the UpdateExpression contains values that do not
- conform to the XSD type of the service’s SDE(s).
- • *IncorrectValueFault: *Indicates that the UpdateExpression contains values that are XSD type conformant, but are not acceptable to the service for other reasons.
- • *PartialFailureFault: *Indicates that servic e was unable to satisfy all portions of the
- UpdateExpression. This fault extends FaultType with an element that contains a list of qnames of SDEs from the UpdateExpression that could not be updated. This fault MAY have 1 or more “faultcause” elements that describe in more detail the portions that failed, using any of the fault types allowed by setServiceData.
- • *Fault*: Any other fault.

## Notification portTypes

- Notification Source
- Source of notification messages. May send to multiple sinks
- Notification Sink
- Receives notification messages from any number of notification sources
- Not required to implement the GridService portType
- NotificationSubscription
- Created from a subscription message and used to manage a subscription

## A Notification Scenario

- NotificationSink

**1**. NotificationSink calls the
- subscribe operation on
- NotificationSource

- NotificationSource

## A Notification Scenario

- NotificationSink

- 1. NotificationSink calls the
- subscribe operation on
- NotificationSource

- NotificationSource

- NotificationSubscription

- 2.NotificationSource creates
- a subscription
- service

## A Notification Scenario

- NotificationSink

**1**. NotificationSink calls the
- subscribe operation on
- NotificationSource

- NotificationSource

- NotificationSubscription

**2**.NotificationSource creates
- a subscription
- service

-                         **3**. Notification
-                Source  returns a
-      locator to the subscription
- service

## A Notification Scenario

- NotificationSink

**1**. NotificationSink calls the
- subscribe operation on
- NotificationSource

- NotificationSource

- NotificationSubscription

**2**.NotificationSource creates
- a subscription
- service

-                         **3**. Notification
-                Source  returns a
-      locator to the subscription
- service

**4.b** The NotificationSink and
- Subscription service interact
- to perform lifetime management

**4.a** deliverNotification
- stream continues
- for the lifetime of
- NotificationSubscription

## Notification Source SDE’s

- notifiableServiceDataName
- A set of QNames of service data elements to which a requestor MAY subscribe for notification of changes.
- <sd:serviceData name=”notifiableServiceDataName” type=”xsd:QName” minOccurs=”0” maxOccurs=”unbounded” mutability=”mutable” modifiable=”false” nillable=”false”/>
- subscribeExtensibility
- A set of operation extensibility declarations (§7.8) for the subscribe operation. Any conforming inputElement declared by values of this SDE MAY be used by the client as a SubscriptionExpression parameter to the instance’s subscribe operation, and implies the subscription semantics and notification message that result from the subscription.
- <sd:serviceData name=”subscribeExtensibility” type=”ogsi:OperationExtensibilityType” minOccurs=”1” maxOccurs=”unbounded” mutability=”static” modifiable=”false” nillable=”false”/>

## Notification Source SDE’s (cont.)

- The NotificationSource portType also includes the following initial service data value elements.
- <sd:staticServiceDataValues> <ogsi:subscribeExtensibility 	    inputElement=”ogsi:subscribeByServiceDataNames” />
- </sd:staticServiceDataValues>

## Notification Source Operations

**NotificationSource :: subscribe**
- Subscribe to be notified of subsequent changes to the target instance’s service data. This operation creates a Grid service subscription instance, which MAY subsequently be used to manage the lifetime and discovery properties of the subscription.
**Input:**
- • *SubscriptionExpression*: The subscription to be performed. This extensible parameter MUST conform to an inputElement declaration denoted by one of the
-      subscribeExtensibility SDE values. Note: The service infers what to do based on the tag of the root element of this argument.
- • *Sink *: The locator of the notification sink to which messages will be delivered. This
-      locator MAY be to some other service than the one issuing this subscription request, thus allowing for third-party subscriptions. This locator MAY contain only references, thus allowing it to refer, for example, to a Web service that implements the NotificationSink portType but that does not have a handle.
- • *ExpirationTime*: The initial time at which this subscription instance should terminate, and thus notification delivery to this sink be halted. Normal GridService lifetime management operations MAY be used on the subscription instance to change its lifetime.

## Notification Source Operations (cont.)

**Output:**
- • *SubscriptionInstanceLocator*: A locator to the subscription instance that was created to manage this subscription. This subscription instance MUST implement the NotificationSubscription portType.
- • *CurrentTerminationTime*: An element of type TerminationTimeType (as defined in §7.6) that gives the NotificationSubscription service's currently planned termination time. The timestamp attribute of this CurrentTerminationTime MUST be the time at which the NotificationSubscription service was created.

## Notification Source Operations (cont.)

**Fault(s):**
- • *ExtensibilityNotSupportedFault: *Indicates that the service cannot evaluate the SubscriptionExpression because its type is not supported by this service.
- • *ExtensibilityTypeFault*: Indicates that the value passed as the SubscriptionExpression violates that value’s type.
- • *TargetInvalidFault*: Indicates that one or more of the SDEs that the SubscriptionExpression requires does not exist in this service.
- • *Fault*: Any other fault.

## Notification Subscription SDE’s

- subscriptionExpression
- The current subscription expression managed by this subscription instance.
- 	<sd:serviceData name=”subscriptionExpression” type=”xsd:anyType” minOccurs=”1” maxOccurs=”1” mutability=”mutable” modifiable=”false” nillable=”false”/>
- sinkLocator
- The Grid Service Locator of the Notification sink to which this subscription is delivering messages.
- 	<sd:serviceData name=”sinkLocator” type=”ogsi:LocatorType” minOccurs=”1” maxOccurs=”1” mutability=”mutable” modifiable=”false” nillable=”false”/>

## Notification Sink Operations

**NotificationSink :: deliverNotification**
- Deliver message to this service.
**Input:**
- • *Message*: An XML element containing the notification message. The content of the message is dependent upon the notification subscription.
- This operation is input-only, so it does not return an output or faults.