This chapter provides a detailed description of the Harmony 4.0 Network Core API. It contains these sections:

Design Overview

The Network Core component operates as a service discovery and message delivery facility. It is responsible for tracking what Network Services are available in the HIS container and making this information available to consumers of its API. It also manages the associations, or bindings, formed by those API consumers and the Network Services and orchestrates the messages that flow between them.

INetworkCore

This interface is the entry point into the Network Core component and defines its public API. Consumers of the API gain access to this interface as an OSGi service. It provides methods for listing all available Network Services or retrieving specific Network Services by type or unique identifier. Consumers are also required to register themselves with the Network Core to receive any events that might be raised.

public void registerClient(INetworkClient client)

Registers the given INetworkClient with the Network Core component. Once registered, the client will begin receiving events generated by the Network Core. Registered clients who wish to no longer receive events should use unregisterClient.

public void unregisterClient(INetworkClient client)

Unregisters the given INetworkClient from the Network Core component. The client will no longer receive events from the Network Core. If the given client was not previously registered, no action is taken.

public List<INetworkService> getNetworkServices()

Returns a list containing all Network Services available to this HIS container. The returned list is a snapshot of the available services and is not dynamically updated after it is returned. Clients interested in receiving real-time updates about available services should review the ServiceMonitor Network Service.

public List<INetworkService> getNetworkServices(String serviceType)

Returns a list containing all Network Services with the given service type available to this HIS container. The returned list is a snapshot of matching services and is not dynamically updated after it is returned. Clients interested in receiving real-time updates about available services should review the ServiceMonitor Network Service.

public INetworkService getNetworkServices(String serviceId)

Returns the Network Service whose unique identifier matches the given string. If no matching service is found, NULL is returned.

INetworkClient

This interface represents a consumer of the Network Core API. It provides information about the client, such as unique identifier and readable name, and methods for delivering messages to the client.

public String getId()

Returns the unique identifier for this client. The identifier must be unique among all client instances. The Network Core does not enforce any particular format for this value, but implementations are encouraged to use a GUID or UUID. The Network Core primarily uses the identifier internally so readability is not necessary.

public String getName()

Returns a human readable name for this client. This name does not have to be unique to all client instances but it is recommended that implementers try to maintain some form of uniqueness to avoid conflicts. There is no specific format required for the client name. However, it is recommended that implementers refrain from using format characters such as carriage returns, line feeds, or tabs.

public void networkCoreShuttingDown()

This method is used to notify the client that the Network Core component is about to end service. It is invoked by the Network Core on all registered clients prior to service interruption. The client should perform any cleanup required such as unbinding of services and resources prior to returning from this function. A client must be registered to receive this notification.

INetworkObject

This interface represents an object available through the Network Core API and is the super interface for INetworkService and INetworkResource. Its methods are common to all Network Core objects and provide information about the object, such as its unique identifier, name, and type.

public String getId()

Returns the unique identifier for this object. The identifier must be unique among all network objects. The Network Core does not enforce any particular format for this value, but implementations are encouraged to use a GUID or UUID. The Network Core primarily uses the identifier internally so readability is not necessary.

public String getName()

Returns a human readable name for this object. This name does not have to be unique to all objects but it is recommended that implementers try to maintain some form of uniqueness to avoid conflicts. There is no specific format required for the object name. However, it is recommended that implementers refrain from using format characters such as carriage returns, line feeds, or tabs.

public String getType()

Returns a string representing the type of this object. This string should follow reverse domain format to avoid naming collisions of objects from different providers, i.e. com.openmethods.iserver.myServiceType.

INetworkService

This interface represents a Network Service provided by a component hosted by the HIS container. It allows the binding and unbinding of clients and provides access to the Network Resources it manages. As Network Service components become available, they declare themselves as OSGi services that implement the INetworkService interface. The Network Core monitors the OSGi container for the addition or removal of OSGi services that implement this interface.

public JsonNode getServiceInfo()

Returns a JSON structure that contains service specific information about this service. This information might include items like vendor name or brief description. JSON is used to provide clients with a common format without placing any requirements on its contents. Service implementers should provide a schema for this structure as part of their documentation.

public List<INetworkResource> getNetworkResources()

Returns the list of INetworkResources currently managed by this Network Service. The returned list is a snapshot of the available resources and is not dynamically updated after it is returned.

public List<INetworkResource> getNetworkResources(String resourceType)

Returns the list of INetworkResources of the given type currently managed by this Network Service. The returned list is a snapshot of the available resources and is not dynamically updated after it is returned.

public INetworkResource getNetworkResource(String resourceId)

Returns the INetworkResource with the given unique identifier. If this Network Service is not currently managing a matching resource, NULL is returned.

public INetworkObjectBinding<INetworkService> bindClient(INetworkClient client)

Requests that the given Network Client be bound to this Network Service. Bound clients will receive events generated by this service through the returned Network Object Binding. Clients can also send requests to this service and receive responses from this service through the returned Network Object Binding.

INetworkResource

This interface represents a Network Resource that is offered by a Network Service. It allows a Network Service to partition its features into sub components to be used by only those clients interested in those features. It can also be used to provide a dedicated view of the Network Service for a specific client or group of clients.

public INetworkService getNetworkService()

Returns the Network Service that manages this Network Resource.

public INetworkObjectBinding<INetworkResource> bindClient(INetworkClient client)

Requests that the given Network Client be bound to this Network Resource. Bound clients will receive events generated by this resource through the returned Network Object Binding. Clients can also send requests to this resource and receive responses from this resource through the returned Network Object Binding.

INetworkObjectBinding<T extends INetworkObject>

This interface represents an association between a Network Client and a Network Object. This interface is parameterized with the type of Network Object that is bound. It provides methods for a client to communicate with and receive events from the bound object. It also provides the ability to release the binding when it is no longer needed.

public INetworkClient getBoundClient()

Returns the Network Client that is bound to the Network Object.

public T extends INetworkObject getBoundObject()

Returns the Network Object that the Network Client is bound to.

public void setListener(INetworkObjectBindingListener listener)

Sets the listener of this binding that will receive events and request responses. This method should be called prior to activate() to ensure no events are missed.

public void activate()

Activates this binding. No requests can be made to this binding and no events will be delivered by this binding until it is activated. The method setListener() should be called prior to calling this method to ensure no events are missed. Some Network Object may generate special events in response to the initial activation of a binding. For instance, the Service Monitoring Network Service sends the entire list of known Network Services to new client bindings so they have a working set to base further add and remove events on.

public void sendRequest(String requestId, JsonNode request)

Makes a request to the bound Network Object. The request id provides a unique identifier for the request that will be included when a response is generated allowing the two messages to be correlated. The request content is provided as a JSON structure and is defined by the underlying Network Object API. The request response is not returned by this method, but is delivered asynchronously through the binding listener. An IllegalState exception is thrown if this binding has not been activated or has been released prior to calling this method.

public void releaseBinding()

Releases this binding and any underlying system resources associated with it. Once called, this binding no longer operational. It will no longer accept new requests or send additional responses or events to the associated listener.

INetworkObjectBindingListener

This interface is used by a Network Object Binding to deliver request responses and events to a Network Client. A single listener can be used for multiple bindings if desired.

public void handleResponse(INetworkObjectBinding<T> binding, String requestId, JsonNode response)

Called by a Network Object Binding to deliver a request response to its bound client. The source binding is provided to allow a listener to be used for multiple bindings. The unique identifier of the initial request is provided to allow correlation between the response and the original request. The response is formatted as a JSON structure and is dependent on the original request, the type of response (success, failure), and the underlying Network Object API.

public void handleEvent(INetworkObjectBinding<T> binding, JsonNode event)

Called by a Network Object Binding to deliver an event to its bound client. The source binding is provided to allow a listener to be used for multiple bindings. The event is formatted as a JSON structure and is dependent on the type of event and the underlying Network Object API.

public void bindingReleased(INetworkObjectBinding<T> binding)

Called by a Network Object Binding to notify the bound client that the binding has been released. This could be invoked as a result of the releaseBinding() method of the binding being called by the client or if the binding was forcefully released by the underlying Network Object.

Client Registration

Although it’s not strictly required for Network Clients to register themselves with the Network Core component, it is highly recommended that they do so prior to calling any Network Core API methods or binding any Network Services or Resources. Registered clients are notified prior to the Network Core component ending service. The Network Core component will wait a reasonable amount of time for registered clients to perform cleanup before ending service. Non-registered clients will have no such opportunity and will have all active bindings summarily unbound without warning and with possible risk of data loss or other adverse effects.

Network Service Binding Cycle

Before a Network Client can communicate with or use the capabilities of a Network Service it must be bound to that service. The following diagram illustrates the typical steps involved in binding a Network Client to a Network Service:

The Network Client registers itself with the Network Core
The Network Client retrieves the current list of available Network Services from the Network Core
The Network Client iterates through the list of services and identifies the desired service
The Network Client calls bindClient() on the Network Service passing itself as the client
The Network Service creates a new Network Object Binding for the Network Client and returns it
The Network Client creates a new Network Object Binding Listener and sets it as the listener for the Network Object Binding
The Network Client activates the Network Object Binding to start receiving events through the listener
The Network Client begins using the Network Service API by making requests and handling responses and events delivered through the binding listener
Once the binding is no longer needed, the Network Client releases the binding
The Network Object Binding requests from the Network Service that its resources be released
Once all the resources are released, the Network Service notifies the binding that it is released
The binding notifies the binding listener that the binding has been released

Service Discovery & Selection

Network Clients wishing to bind to a Network Service and leverage its capabilities or listen to its events must first obtain a reference to it. The Network Core API has a few different methods for locating Network Services. The most general method, getNetworkServices(), simply returns a snapshot of the Network Services currently known to the Network Core component. The Network Client can iterate through this list and locate the desired service based on its id, name, type, or service specific information.

The returned list of Network Services can also be pre-filtered by providing the type of Network Service the Network Client is looking for. This can be useful if the search parameters depend on data contained within the service specific information structure, as Network Services with the same type should have similar informational structures.

Finally, if the Network Client happens to already know the unique identifier for the desired Network Service, it can request that service directly. This method is often used in the case of “well known” services that always carry the same unique identifier such as the built-in Service Monitor Network Service.

Network Clients can also choose to leverage the real-time event based registry service provided by the Network Core component called the Service Monitor Network Service. After an initial list of all services, it provides events to bound clients when a service is added or removed from the list.

Network Resource Binding Cycle

The process of binding a Network Resource is similar to binding a Network Service if the resource is long running and already initialized by its parent Network Service. These resources are usually referred to as Static Network Resources. However, some Network Resources are transient and are created upon request by the parent Network Service. These resources are usually referred to as Dynamic or Instance Network Resources. Both scenarios are illustrated in the following diagrams.

Binding Static Network Resources

The Network Client retrieves the list of Network Resources managed by the Network Service
The Network Client iterates through the resource list and locates the desired Network Resource
The Network Client binds itself to the Network Resource
The Network Resource creates a new Network Object Binding for the requesting Network Client and returns it
The Network Client creates a new Network Object Binding Listener and sets it on the returned resource binding
The Network Client activates the resource binding
When the binding is no longer needed, the Network Client releases the resource binding
The resource binding requests that the Network Resource dispose of any system resources associated with the resource binding
The resource binding notifies the binding listener that the resource binding has been released

Static Resource Discovery & Selection

Network Clients wishing to bind to a Static Network Resource and leverage its capabilities or listen to its events must first obtain a reference to it. The Network Service API has a few different methods for locating Network Resources. The most general method, getNetworkResources(), simply returns a snapshot of the Network Resources currently known to the Network Service. The Network Client can iterate through this list and locate the desired resource based on its id, name, or type.

The returned list of Network Resources can also be pre-filtered by providing the type of Network Resource the Network Client is looking for. If the Network Client happens to already know the unique identifier for the desired Network Resource, it can request that resource directly. This method is often used in the case of “well known” resources that always carry the same unique identifier.

Unlike the Network Core component, a Network Service is not required to expose a Network Resource that provides a real-time resource registry for the Network Service. It is however highly recommended that Network Service implementers do so and follow the same pattern used for the Service Monitor Network Service provided by the Network Core component.

Binding Dynamic Network Resources

It is important to note that unlike binding a Static Network Resource, a Network Client must be bound to the parent Network Service to create the Dynamic Network Resource and then bind to it. After this key difference, the flows are identical for Static and Dynamic Network Resources.

After the Network Client is bound to a Network Service, it sends a request for access to a Dynamic Network Resource through its service binding
The Network Service creates the new Dynamic Network Resource and returns identifying information to the client in the response to the initial request
The Network Client retrieves a reference to the newly created Dynamic Network Resource from the Network Service by using the provided information in the response
The Network Client then continues on to bind to the Network Resource
The remaining flow is identical to using Static Network Resources

Requesting Dynamic Network Resources

The process of requesting a Dynamic Network Resource and the structure and contents of the request messages are Network Service specific. Not all Network Services will offer Dynamic Network Resources. The Network Service implementer should document the use of Dynamic Network Resources and illustrate how they are created and managed.

Limit to Bound Clients

Some Network Resources, usually ones that are Dynamic, only allow a single Network Client to be bound at a time. The resource might allow multiple bound clients, but only a specific set of clients are authorized to form a binding. An error is generated during resource binding if one of these constraints is in place and the binding fails to meet the requirement.