This chapter provides a detailed description of the Harmony 4.0 Network Core API. It contains these sections:
· Network Service Binding Cycle
· Network Resource Binding Cycle
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.
...
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.
...
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.
...
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.
...
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.
...
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.
...
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.
...
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.
...
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
...
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
...