Discovery API

Discovery architecture

In order to gather information on the SOA, EasySOA offers an API allowing service discovery sources to tell the registry about services that it sees. Since the same document can get information from several sources (monitoring, SCA import, etc.), this service is a low-level way to deal with the model without being concerned about the whole document structure or having to know which metadata can be overridden.

TODO refactor architecture and wiki by replacing "notification" by "discovery"

Classes

All these classes are stored in the easysoa-model-demo-core bundle.

• org.easysoa.services.NotificationService is the core of all notifications. It allows you to notify the model just by calling the needed method (ex: notifyService()).

• org.nuxeo.runtime.api.Framework is what allows you to get access to the notification service :

         Framework.getRuntime().getService(NotificationService.class);
  

• org.easysoa.doctypes.* allow you to get access to the different properties of each document as constants. They also provide some documentation on the role of each property.

Some existing uses of the service (as examples)

• easysoa-model-demo-core / org.easysoa.sca.visitors.ServiceBindingVisitorBase.visit()
• easysoa-model-demo-core / org.easysoa.sca.visitors.ReferenceBindingVisitorBase.visit()
• easysoa-model-demo-rest / org.easysoa.rest.NotificationRest.doPostXXX()

REST API

The EasySOA API based on this notification system, is used to create or update all document types specific to the registry (Appli Impls, APIs, Services). This API is mainly used by:

• The Discovery by Monitoring feature
• The Discovery by Browsing feature Since the SCA imports are done from Nuxeo itself, they can directly access the notification classes.

See Accessing the soa model remotely for developer information on this API.

Behavior

Each notification allows to create or update one specific document. What acts as a key to select a document is the URL property, implying this property is mandatory for all notifications. If a document with given URL already exists, the according document is updated, else a new document will be created.

Except for Appli Impls, all documents will also need a ParentURL property, that allows to know where the document has to be sorted. If no document match the parent URL, a new document is created to store the notified document. In addition, providing a new parent URL to a document allows to move it.

All properties (except URL and ParentURL) that are given as parameters overwrite any information on the document.

About the Default Application

The service registry contains by default an empty Appli Impl. called "Default Application". It is used to store all APIs and Service where poor information is known, and acts as a transition point before new notifications move the documents to the related applications.

Specific behavior and examples

For REST examples, see Accessing the SOA model through REST.

Application notification

• Required properties: URL

Example

TODO

ServiceAPI notification

• Required properties: URL
• Default behavior: If no parent URL is provided, the API is stored in the Default Application.

Example

TODO

Service notification

• Required properties: URL, parent URL
• Default behavior: If the parent URL refers to an API that doesn't exist, it is created in the Default Application.
• If a WSDL is attached to the service (thanks to the file URL property), it is analyzed to extract relevant information.
• In order to compute an unknown API URL from the Service URL, you can use the ServiceNotification.computeApiUrl() method.

Example

TODO

Reference notification

• Required properties: Architecture path, parent URL
• Default behavior: Fails if the given parent URL refers to an Appli Impl. that doesn't exist.

Example

TODO