ContextServer

From MobiComp

For installation details, see Context Server Installation.

Contents 1 Source code 2 HTTP GET requests 2.1 Registering an entity 2.2 Inserting context elements into the store 2.3 Retrieving context elements from the store 2.4 Removing context elements from the store 3 HTTP POST requests 3.1 Registering an entity 3.2 Inserting context elements into the store 3.3 Retrieving context elements from the store 3.4 Removing context elements from the store

Source code

Most of the servlet functionality is in the base class ContextServletBase.java. Two subclass versions differ only in initialisation parameters and choice of storage method used by the associated ContextService. The server version of ContextServlet.java typically runs under Tomcat and uses a PostgreSQL back end. The client version runs with whatever local servlet container is available. For example, the version used with FieldMap is normally used with the LWS server.

The servlet responds differently to GET and POST requests. GET requests typically come from a web browser and return an HTML page. POST requests are expected to contain an XML document encoding the request and return an XML document containing the servlet response.

HTTP GET requests

A query string containing the following:

cmd: a command, one of register, put, get, remove.

Registering an entity

• register: register a new context entity. Requires the following parameters:

name: a string that will be recorded as entity.name

description: a string that will be recorded as entity.description

type: a string that will be recorded as entity.type

Example:

  http://<server-host>/Context/ContextServlet?cmd=register&name=fe40009668&type=RFID tag&description=Unique/EM4102 tag, laminated card

This method is normally only used for manually registering passive objects. Active objects register themselves and other objects using the HTTP POST version. A simple registration form is available at http://<server-host>/Context/regform.html.

Inserting context elements into the store

• put: insert the supplied context element into the store. Requires the following parameters:

subject: id of the context entity

source: (optional) if present, the id of the entity asserting this context element. Normally, this would not be used except to specify the id of a person asserting the context of another object. The person would, of course, need to already exist as a registered entity.

predicate: predicate name of the supplied element

value: a string containing the element value or 'object'

Example:

  http://<server-host>/Context/ContextServlet?cmd=put&subject=b63ca8de3b26319bc8dc84afac6b6b9e&predicate=location.name&value=Canterbury

Note that only simple string values should be put in this way. Even if the value is XML encoded, the server will always treat the value as a string. Unlike the HTTP POST version, it is not possible to specify a different data type for the value object.

Retrieving context elements from the store

• get: retrieve specified context elements. The cmd=get parameter is optional as requests without a cmd parameter are treated as implicit get requests. Returned context list may be restricted as follows:

no parameters: return all current context elements for all entities

http://<server-host>/Context/ContextServlet

subject: restricts elements to the specified context entity id.

predicate: restricts elements to the specified predicate name.

http://<server-host>/Context/ContextServlet?cmd=get&subject=b63ca8de3b26319bc8dc84afac6b6b9e
http://<server-host>/Context/ContextServlet?subject=b63ca8de3b26319bc8dc84afac6b6b9e
http://<server-host>/Context/ContextServlet?subject=b63ca8de3b26319bc8dc84afac6b6b9e&predicate=location.name

optionally, plus either XPath or temporal parameters:

XPath parameters:

xpath: a simple XPath expression representing an XML element or attribute within the stored ContextElements. If present, the content of the element/attribute is tested for equality with the value parameter.

value: a string to compare with the element/attribute indicated by the xpath parameter. An SQL 'LIKE' expression is used to test the value, so wildcards may be included by using '%25' representing the SQL '%' wildcard character.

http://<server-host>/Context/ContextServlet?predicate=name&xpath=//object&value=MobiComp2490_01
http://<server-host>/Context/ContextServlet?predicate=name&xpath=//object&value=MobiComp2490%25

all: setting the all parameter to true (t, true, y, yes, 1) changes the query behaviour to return all ContextElements associated with the subject of the query result. For example,

http://<server-host>/Context/ContextServlet?predicate=name&xpath=//object&value=MobiComp2490_01&all=true

returns all elements for the entity named MobiComp2490_01, and

http://<server-host>/Context/ContextServlet?predicate=type&xpath=//object&value=RFID%20tag&all=yes

returns all elements for each of the entities with the type RFID tag.

Temporal parameters, one or both of:

from: returns all elements valid at or after the specified ISO format date or timestamp.

to: returns all elements valid at or before the specified ISO format date or timestamp.

http://<server-host>/Context/ContextServlet?subject=b63ca8de3b26319bc8dc84afac6b6b9e&predicate=location.name&from=2006-11-01

Removing context elements from the store

• remove: remove the specified context element from the store. Requires the following parameters:

subject: id of the context entity

predicate: predicate name of the element to be removed

Example:

  http://<server-host>/Context/ContextServlet?cmd=remove&subject=b63ca8de3b26319bc8dc84afac6b6b9e&predicate=location.name

HTTP POST requests

This is the normal mode of interaction between a local ContextService on a device and the main server. Request content is expected to be an ConteXtML Document, containing either a <register> element, or one or more <put>, <get> or <remove> elements.

Registering an entity

Client sends a document containing a single <register> element with mandatory name, type and description attributes:

    <?xml version="1.0" encoding="UTF-8"?>
    <context xmlns="http://www.mobicomp.org/ConteXtML">
      <register name="xxx" type="yyy" description="zzz"/>
    </context>

If successful, an entity ID is generated and the name and description parameters are used to set the entity name and description values in the store. The server returns the following document in which the <register> element contains the entity ID:

    <?xml version="1.0" encoding="UTF-8"?>
    <context xmlns="http://www.mobicomp.org/ConteXtML">
      <service url="http://www.mobicomp.org/Context/ContextServlet"/>
      <response value="ok"/>
      <register id="123456789abcdef0123456789abcdef0"/>
    </context>

Inserting context elements into the store

Client sends a document containing one or more <put> elements, each containing one or more <contextElement> elements, for example:

    <?xml version="1.0" encoding="UTF-8"?>
    <context xmlns="http://www.mobicomp.org/ConteXtML">
      <put>
        <contextElement privacy="public" timestamp="1071250425039">
          <subject>4da941681d39c92095e73fc59f2c1076</subject>
          <predicate>velocity</predicate>
          <object type="org.mobicomp.spatial.Velocity">
            <velocity>
              <speed unit="m/s">33.0</speed> 
              <dir>231.5</dir> 
            </velocity>
          </object>
        </contextElement>
      </put>
    </context>

In most cases, an client will be posting its own context to the server. Here the client is both the subject and the observer, and identified by the MobiComp identifier in the <subject> element. When a client needs to post information about another entity, typically a passive entity that cannot post its own context, the <source> element is used to identify the observer/sender, and the <subject> identifies the entity to which the context refers:

          ...
          <source>1921176554400a5be91e46e735c67024</source>
          <subject>4da941681d39c92095e73fc59f2c1076</subject>
          <predicate>velocity</predicate>
          ...

On success the element is inserted into the store and the server returns:

    <?xml version="1.0" encoding="UTF-8"?>
    <context xmlns="http://www.mobicomp.org/ConteXtML">
      <service url="http://www.mobicomp.org/Context/ContextServlet"/>
      <response value="ok"/>
    </context>

Retrieving context elements from the store

Client sends a document containing one or more <get> elements. If subject and/or predicate attributes are empty or missing, they are treated as wildcards. For example:

    <?xml version="1.0" encoding="UTF-8"?>
    <context xmlns="http://www.mobicomp.org/ConteXtML">
      <get subject="4da941681d39c92095e73fc59f2c1076" predicate="velocity"/>
    </context>

plus, optionally, either temporal or XPath attributes:

Temporal attributes:

'from' and 'to' attributes may specify a timestamp range (ISO format) to retrieve a range of historical elements. If only 'from' is supplied, all elements from the specified date up to and including the current element are returned. If only 'to' is supplied, all elements up to and including those current at the specified date are returned.

    <?xml version="1.0" encoding="UTF-8"?>
    <context xmlns="http://www.mobicomp.org/ConteXtML">
      <get subject="4da941681d39c92095e73fc59f2c1076" predicate="velocity" from="2004-01-01" to="2004-01-31"/>
    </context>

XPath attributes:

'xpath', 'val' and, optionally, 'all' attributes may specify a child of the XML ContextElement and a value to test for equality. Both cpath and val parameters must be present. For example, if the object corresponding to a 'bluetooth' predicate name has child elements /device/addr, the following will retrieve the ContextElement with the specified addr value (if any match).

    <?xml version="1.0" encoding="UTF-8"?>
    <context xmlns="http://www.mobicomp.org/ConteXtML">
      <get predicate="bluetooth" xpath="//object/device/addr" val="08:00:46:e0:2a:24"/>
    </context>

On success the specified elements are returned:

    <?xml version="1.0" encoding="UTF-8"?>
    <context xmlns="http://www.mobicomp.org/ConteXtML">
      <service url="http://www.mobicomp.org/Context/ContextServlet"/>
      <response value="ok"/>
      <contextElement privacy="public" timestamp="1071250425039">
        <subject>1921176554400a5be91e46e735c67024</subject>
        <predicate>bluetooth</predicate>
        <object type="org.mobicomp.context.ContextObject">
          <device type="bluetooth">
            <name>herodotus</name>
            <addr>08:00:46:e0:2a:24</addr>
          </device>
        </object>
      </contextElement>
    </context>

The all attribute: setting all to true (t, true, y, yes, 1) changes the query behaviour to return all ContextElements associated with the subject of the query result. For example,

    <?xml version="1.0" encoding="UTF-8"?>
    <context xmlns="http://www.mobicomp.org/ConteXtML">
      <get predicate="type" xpath="//object" val="PDA" all="true"/>
    </context>

will return all context elements for every entity with the type PDA.

Removing context elements from the store

Client sends a document containing one or more <remove> elements. If subject and/or predicate attributes are empty or missing, they are treated as wildcards. For example:

    <?xml version="1.0" encoding="UTF-8"?>
    <context xmlns="http://www.mobicomp.org/ConteXtML">
      <remove subject="4da941681d39c92095e73fc59f2c1076" predicate="velocity"/>
    </context>

On success the element is removed into the store and the server returns:

    <?xml version="1.0" encoding="UTF-8"?>
    <context xmlns="http://www.mobicomp.org/ConteXtML">
      <service url="http://www.mobicomp.org/Context/ContextServlet"/>
      <response value="ok"/>
    </context>