diffusion/README.md

Diffusion JavaScript client

## Diffusion JavaScript API

The Diffusion JavaScript API allows interaction with a Diffusion server from both
the browser and Node.js.

Clients use a WebSocket or HTTP connection to send and receive, as well as perform
other functions such as adding, removing or updating topics. 


### Quick start

A client Session maintains a connection to the server. To create a session, simply do
 
```javascript
 diffusion.connect('diffusion.example.com');
```

 It is also possible to connect with a map of options
 
```javascript
 diffusion.connect({
    host : 'diffusion.example.com',
    port : 8080,
    secure : false,
    principal : 'admin',
    credentials : 'password'
 });
```

Connecting returns a [Promise](https://promisesaplus.com/) - this will succeed if the session could be connected, or fail if not.

```javascript
diffusion.connect('diffusion.example.com').then(function(session) {
    // Connected!
}, function(error) {
    // Failed to connect :(
});
```

Sessions emit events to indicate their status such as when they are disconnected or closed.
These events are easy to listen to:

```javascript
session.on('disconnect', function(reason) {
    // Lost connection to the server!
});

session.on('close', function() {
    // Session is closed!
});
```

Once a session is closed, it can never be re-opened.


#### Subscriptions

Data in Diffusion is distributed via *topics*. A topic has state, which
can be updated. The state can be simple - such as a string or an integer - or more complex - such as 
a JSON document. Each topic has a unique path and is addressed through a [topic selector](TopicSelector.html).

The way that a session receives data is by subscribing. Subscriptions allow the session to select one or more
topics to receive values from. A session may subscribe to many topics, as well as subscribe to the same topic 
multiple times.

```javascript
session.select('topic/foo')
```

To attach listeners for received values, a [ValueStream](ValueStream.html) is used. The stream that is 
returned will emit events when the value of the selected topic changes.

```javascript
session.addStream('topic/foo', diffusion.datatypes.json()).on('value', function(topic, specification, newValue, oldValue) {
    // Do something with the value
    var value = newValue.get();
});
```
It is possible to register any number of streams to a subscription's events. They will each be called when a new
value is received.

### Contents

The JavaScript client provides namespaces, classes, and methods that support the following capabilities:

#### Basics

*   Connect the JavaScript client to Diffusion or Diffusion Cloud by using the [diffusion.connect](diffusion.html#connect) method.

*   To change the security principal that the client is connected with, use the [changePrincipal](Session.security.html#changePrincipal) method.

*   The client can log out information by using the [diffusion.log](diffusion.html#log) method.

*   The client can check its connectivity and roundtrip time to the server by using the [pingServer](Session.html#pingServer) method.


#### Receive data from topics

*   Subscribe to topics.    
    Use the [session.select](Session.html#select) method to subscribe to a topic.
    The updates to a topic can be interacted with by registering a [ValueStream](ValueStream.html) and a provided datatype to start receiving 
    the values of that datatype.    

*   Fetch data from topics.    
    Use the [fetch](Session.html#fetch) method to make a fetch request and get a [FetchStream](FetchStream.html) object that you can use to receive fetched values.


#### Create and manage topics

*   Add a topic.    
    Use the [add](Session.topics.html#add) method to add a topic. You can create a topic by explicitly defining the topic type, or by providing a 
    [TopicSpecification](TopicSpecification.html) with optional properties.

*   Handle missing topics.    
    Use the [addMissingTopicHandler](Session.topics.html#addMissingTopicHandler) method to register a [MissingTopicHandler](MissingTopicHandler.html).
    This handler receives a [MissingTopicNotification](MissingTopicNotification.html) when a client session subscribes to a topic that does not currently exist. 
    The notified client can then choose to create that topic if appropriate.

*   Remove topics.  
    Use the [remove](Session.topics.html#remove) method to remove topics. You can also mark topics to be removed automatically with the TopicSpecification property
    [REMOVAL](TopicSpecification.html#REMOVAL).


#### Update topics

*   Update a topic non-exclusively by using the [update](Session.topics.html#update) method.

*   Update a topic exclusively.    
    Use the [registerUpdateSource](Session.topics.html#registerUpdateSource) method to register a [TopicUpdateHandler](TopicUpdateHandler.html) to perform 
    updates on a topic. 

*   Update topics by using the classes in the [diffusion.datatypes](diffusion.datatypes.html) namespace to create update values.


#### Manage other clients

*   Subscribe other client sessions to topics.    
    Use the [select](Session.clients.html#select) and [unsubscribe](Session.clients.html#unsubscribe) methods in [Session.clients](Session.clients.html) 
    namespace to manage another client session's subscriptions.
    
*   Receive notifications about other sessions and their properties.    
    Use the [setSessionPropertiesListener](Session.clients.html#setSessionPropertiesListener) method to register 
    a [SessionPropertiesListener](Session.clients.SessionPropertiesListener.html) to receive notifications for session events or when a session changes properties.
    
*   Query the session properties of a specific session.    
    Use the [getSessionProperties](Session.clients.html#getSessionProperties) method. Specify which sets of properties to receive using 
    [PropertyKeys](diffusion.clients.html#.PropertyKeys).


#### Send messages

*   Send a message.    
    Use the [send](Session.messages.html#sendRequest) method to either send a message to a specific client session or 
    send a [message](Session.messages.html#toc14) to a path.
    
*   Receive messages sent to this client session.    
    Use the [setRequestStream](Session.messages.html#setRequestStream) method to receive messages sent to this client session through 
    a [RequestStream](Session.messages.RequestStream.html).

*   Receive messages sent to a path.    
    Use the [addRequestHandler](Session.messages.html#addRequestHandler) method to register a [RequestHandler](Session.messages.RequestHandler.html) that receives 
    messages sent to a path.


#### Authenticating clients

*   Register an authentication handler to authenticate other client sessions.    
    Implement an [AuthenticationHandler](AuthenticationHandler.html) and use the [setAuthenticationHandler](Session.security.html#setAuthenticationHandler) 
    method to register it with the server.
    
The server also uses information stored in the system authentication store to authenticate connecting clients.

*   Get the system authentication store information with the 
    [getSystemAuthenticationConfiguration](Session.security.html#getSystemAuthenticationConfiguration) method.     

*   Update the system authentication store.    
    Use the [authenticationScriptBuilder](Session.security.html#authenticationScriptBuilder) method to get a 
    [SystemAuthenticationScriptBuilder](SystemAuthenticationScriptBuilder.html). The builder can be used to create a script. Pass the script 
    to the [updateAuthenticationStore](Session.security.html#updateAuthenticationStore) method to update the system authentication store.  


#### Updating security roles

*   Get the security store information [getSecurityConfiguration](Session.security.html#getSecurityConfiguration) method.

*   Update the security store.    
    Use the [securityScriptBuilder](Session.security.html#securityScriptBuilder) method to get a [SecurityScriptBuilder](SecurityScriptBuilder.html). The 
    builder can be used to create a script. Pass the script to the [updateAuthenticationStore](Session.security.html#updateAuthenticationStore) method to update 
    the system authentication store.