N.S.R. means Narrative State Repository. Thanks to it, multiple entities can share data (identifier and value pairs) using the Publish/subscribe pattern (http://en.wikipedia.org/wiki/Publish/subscribe). Entities can also consult data without subscribing to them.
Run run.bat (Windows only)/run.sh (UNIX based systems only).
You can also run N.S.R. in a shell environment using command lines. Type java -jar sse.jar <service_port> <print_output> from the N.S.R. directory. <service_port> is the port N.S.R. listens to incoming connections. <print_output> turns N.S.R. into verbose mode (expected values are true or false).
N.S.R. quits on the KILL signal: ensure that the console that is running N.S.R. has the focus, then maintain the CTRL key and hit the C key.
Entities can connect to N.S.R. using TCP sockets. The hostname/IP of N.S.R. is the hostname/IP of the machine running the program. The default port is 56789 if N.S.R. was launched from script, otherwise it's the port given from the command line.
Most of the time, no acknowledgement or error message is emmitted from N.S.R.. Have a look at the console if N.S.R. is in verbose mode, N.S.R. status is printed out every time an incoming message has been processed.
N.S.R. expects XML messages encoded in UTF-8. Each message must be formated according to a pre-defined schema. Messages that don't fulfill the schema are rejected without warning.
In the subscription procedure, entities must indicate N.S.R. the identifiers of the data they want to subscribe to.
Entities will then receive data values as soon as they are published. If values have already been published, entities will instantly be notified with a status message.
Subscriptions must fulfill the following schema:
<element name="subscribe">
<complexType>
<sequence>
<element name="data" maxOccurs="unbounded">
<complexType>
<attribute name="id" use="required" type="string" />
</complexType>
</element>
</sequence>
</complexType>
</element>
Status fulfill the following schema:
<element name="status">
<complexType>
<sequence>
<element name="data" maxOccurs="unbounded">
<complexType>
<simpleContent>
<extension base="string">
<attribute name="id" use="required" type="string" />
</extension>
</simpleContent>
</complexType>
</element>
</sequence>
</complexType>
</element>
Here's an example where some entity subscribe to data1 and data2:
<subscribe>
<data id="data1"/>
<data id="data2"/>
</subscribe>
data1 is already known from N.S.R. and data2 hasn't already been published, thus the entity is sent a status message with the value of data1:
<status>
<data id="data1">42</data>
</status>
This is the reverse procedure of subscribe. Entities must indicate N.S.R. the identifiers of the data they want to unsubscribe to.
Unsubscribe messages must fulfill the following schema:
<element name="unsubscribe">
<complexType>
<sequence>
<element name="data" maxOccurs="unbounded">
<complexType>
<attribute name="id" use="required" type="string" />
</complexType>
</element>
</sequence>
</complexType>
</element>
Entities can publish data over N.S.R.. They don't need to be subscribed to any data to perform this operation.
As soon as data are published, entities which have subscribed to them will be instantly notified with a push message.
Publishing messages must fulfill the following format:
<element name="publish">
<complexType>
<sequence>
<element name="data" maxOccurs="unbounded">
<complexType>
<simpleContent>
<extension base="string">
<attribute name="id" use="required" type="string" />
</extension>
</simpleContent>
</complexType>
</element>
</sequence>
</complexType>
</element>
Push messages fulfill the following format:
<element name="push">
<complexType>
<sequence>
<element name="data" maxOccurs="unbounded">
<complexType>
<simpleContent>
<extension base="string">
<attribute name="id" use="required" type="string" />
</extension>
</simpleContent>
</complexType>
</element>
</sequence>
</complexType>
</element>
Here's an example where some entity publishes values of data1 and data2:
<publish>
<data id="data1">67</data>
<data id="data2">89</data>
</publish>
Some entity has had subscribed to data1 then it receives a push message:
<push>
<data id="data1">67</data>
</push>
Some other entity has had subscribed to data2 then it also receives a push message:
<push>
<data id="data2">89</data>
</push>
Entities can consult data they haven't subscribed to any time. They just have to send a query to N.S.R., then it instantly provides the result to the entities.
Queries must fulfill the following schema:
<element name="query">
<complexType>
<sequence>
<element name="data" maxOccurs="unbounded">
<complexType>
<attribute name="id" use="required" type="string" />
</complexType>
</element>
</sequence>
</complexType>
</element>
Results fulfill the following schema:
<element name="result">
<complexType>
<sequence>
<element name="data" maxOccurs="unbounded">
<complexType>
<simpleContent>
<extension base="string">
<attribute name="id" use="required" type="string" />
</extension>
</simpleContent>
</complexType>
</element>
</sequence>
</complexType>
</element>
Here's an example where some entity queries N.S.R. for data1:
<query>
<data id="data1"/>
</query>
Then N.S.R. replies:
<result>
<data id="data1">67</data>
</result>
N.S.R. detects entities disconnection. Corresponding unsubscribe operations are then automatically performed.