Derivatives of RestService

Derivatives of RestService interface facilitates creation of RESTful implementation of standard services.

Simple search (simple-search)

The following are the specialized interfaces and classes available for the simple-search service:
  • com.hcl.unica.system.integration.service.search.RestSearchService

    The com.example.service.rest.SimpleSearchService class in asset-integration-starter project is a quick starter implementation for RESTful simple-search service. Its parent is com.hcl.unica.system.integration.service.search.RestSearchService class.

    The RestSearchService class has a type parameter RS, which represents the type of response (post deserialization) received from the remote REST API. In this case it is SimpleSearchResponse class defined inside the asset-integration-starter project.

    RestSearchService class implements RestService interface and defines the SearchRequest class as the type argument RQ for RestService. Thus, the object of SearchRequest becomes input to all the simple-search services (same input is used for Functional counterpart of simple-search as well). SearchRequest class is part of the Content Integration SDK.

    In addition to defining the input type for the simple-search service, RestSearchService class also overrides the transformResponse method and defines return value of this method to be of ContentPage type. ContentPage is also part of the Content Integration SDK and encapsulates the search result and associated pagination details.

    The plugin must extend its simple-search implementation from the service com.hcl.unica.system.integration.service.search.RestSearchService to be recognized as a simple-search service by the Content Integration Framework (Functional counterpart, discussed later, is also a valid choice to extend from, for the simple-search services implemented using the Functional approach).

    RestSearchService extends from com.hcl.unica.system.integration.service.search .AbstractSearchService abstract class.

    We recommend looking at com.aem.service.AemSimpleSearchService class from the aem-integration project to know more about how the SearchRequest class and the ContentPage class are used during service implementation.

    Adhering to the contract of Presentable interface while populating list of contents in ContentPage is a crucial part of this service implementation. Presentable interface is covered in more detail in subsequent section.

  • com.hcl.unica.system.integration.service.search.AbstractSearchService

    This is a common base class for RESTful as well as Functional simple-search implementations. So, the details of this class also apply to the Functional implementation of simple-search.

    This class defines the com.hcl.unica.system.integration.service.gateway.SimpleSearchServiceGateway interface as the service gateway for the simple-search service. ServiceGateways are the means to programmatically define input and output types of the service and the work with the service. A closer look at this interface tells us that the simple-search takes the SearchRequest object and returns the ContentPage object.

    In addition to defining the service interface for simple-search, it introduces one more method for the simple-search service, named getSupportedContentTypes. Every simple-search implementation can optionally override and implement this method. Please note that this method is very simple-search specific and has nothing to do with other standard and custom services. The signature of this method is as follows:
    public Map<String, String> getSupportedContentTypes();

    Implementation of this method returns a Map<String, String> representing the supported categories of contents that can be searched in the target system. There is no specific semantic associated with the entries in this Map. It can be any meaningful key-value pair. It acts as a filter for client application during the search operation. As of current implementation of Unica Content Integration, this Map is used to populate entries in a drop down, wherein keys of the Map become values of the options, and values of the Map become display labels for the options. Thus, keys can carry internal names, or identifiers, and values should be readable and meaningful texts. If the user needs to search any specific type of content, he can choose one or more options from the supported types. In such case, simple-search service receives a set of keys corresponding to the values chosen by the user. Set of keys received from the client application can be obtained from ExecutionContext object by navigating through the getRequest method and then calling getTypes() on it. The simple-search implementation deals with these set of keys, as per the target system’s programming interface, and filters the search items accordingly.

    Standard service parameter - supportedContentTypes

    Overriding getSupportedContentTypes method is recommended only if the Map needs to be generated dynamically. Content Integration Framework provides an alternate approach to statically define this Map using a standard service parameter called supportedContentTypes, configured under params element in the service declaration file. For example, refer the simple-search service declaration for AEM and WCM inside <ASSET_PICKER_HOME>/conf/plugin-services.yml file.

List content categories (list-content-categories)

The following are the specialized interfaces and classes available for the list-content-categories service:

  • com.hcl.unica.system.integration.service.content.categories.list. RestContentCategoriesListService

    The com.example.service.rest. ExampleContentCategoryListingService class in asset-integration-starter project is a quick starter for RESTful list-content-categories service. ExampleContentCategoryListingService class extends from RestContentCategoriesListService class.

    The RestContentCategoriesListService class has a type parameter RS, which represents the type of response (post deserialization) received from the remote REST API. In this case it is specified as List<ContentCategoryDetails> for the sake of example.

    RestContentCategoriesListService class implements RestService interface and defines the com.hcl.unica.system.model.request.content.categories.ContentCategoryListRequest class as the type argument RQ for RestService. Thus, the object of ContentCategoryListRequest becomes input to all the list-content-categories services (same input is used for Functional counterpart of list-content-categories as well).

    In addition to defining the input type for the list-content-categories service, RestContentCategoriesListService class also overrides the transformResponse method and mandates the return value of this method to be an object of List<ContentCategory> type. ContentCategory class is part of Content Integration SDK.

    The plugin must extend the implementation of list-content-categories service from com.hcl.unica.system.integration.service.content.categories.list. RestContentCategoriesListService class to be recognized as a valid list-content-categories service by the Content Integration Framework (Functional counterpart, discussed later, is also a valid choice to extend from).

    RestContentCategoriesListService extends from 
    com.hcl.unica.system.integration.service.content.categories.list.AbstractContentCategoriesListService class
    .

  • com.hcl.unica.system.integration.service.content.categories.list.AbstractContentCategoriesListService

    This is a common base class for RESTful as well as Functional implementations of list-content-categories service. So, the details covered herein applies to Functional version of list-content-categories as well.

    This class defines the com.hcl.unica.system.integration.service.gateway.ContentCategoriesListServiceGateway interface as the service gateway for the list-content-categories service. This interface extends from com.hcl.unica.system.integration.service.gateway. ServiceGateway interface and mandates the ContentCategoryListRequest & List<ContentCategory> objects to be the input and output types for the list-content-categories service.

List folders (list-folders)

The following are the specialized interfaces and classes available for the list-folders service:

  • com.hcl.unica.system.integration.service.folder.list.RestFolderListService

    The com.aem.service.AemFolderListService class in aem-integration project is a reference implementation for RESTful list-folders service. AemFolderListService class extends from RestFolderListService class.

    The RestFolderListService class has a type parameter RS, which represents the type of response (post deserialization) received from the remote REST API. In this case it is SimpleSearchResponse class defined inside the aem-integration project.

    RestFolderListService class implements RestService interface and defines the com.hcl.unica.system.model.request.folder.list.FolderListRequest class as the type argument RQ for RestService. Thus, the object of FolderListRequest becomes input to all the list-folders services (same input is used for Functional counterpart of list-folders as well).

    In addition to defining the input type for the list-folders service, RestFolderListService class also overrides the transformResponse method and mandates the return value of this method to be an object of List<Folder> type. Folder is a standard type defined in Content Integration SDK.

    The plugin must extend the implementation of list-folders service from com.hcl.unica.system.integration.service.folder.list.RestFolderListService class to be recognized as a valid list-folders service by the Content Integration Framework (Functional counterpart, discussed later, is also a valid choice to extend from).

    RestFolderListService extends from com.hcl.unica.system.integration.service.folder.list.AbstractFolderListService class.

  • com.hcl.unica.system.integration.service.folder.list. AbstractFolderListService

    This is a common base class for RESTful as well as Functional implementations of list-folders service. So, the details covered herein applies to Functional version of list-folders as well.

    This class defines the com.hcl.unica.system.integration.service.gateway.FolderListServiceGateway interface as the service gateway for the list-folders service. This interface extends from com.hcl.unica.system.integration.service.gateway.ServiceGateway interface and mandates the FolderListRequest and List<Folder> objects to be the input and output types for the list-folders service.

List contents (list-contents)

The following are the specialized interfaces and classes available for the list-contents service:

  • com.hcl.unica.system.integration.service.content.list.RestContentListService

    The com.aem.service.AemContentListServiceclass in aem-integration project is a reference implementation for RESTful list-contents service. AemContentListServiceclass class extends from RestContentListService class.

    The RestContentListService class has a type parameter RS, which represents the type of response (post deserialization) received from the remote REST API. In this case it is SimpleSearchResponse class defined inside the aem-integration project.

    RestContentListService class implements RestService interface and defines the com.hcl.unica.system.model.request.content.list.ContentListRequest class as the type argument RQ for RestService. Thus, the object of ContentListRequest becomes input to all the list-contents services (same input is used for Functional counterpart of list-contents as well).

    In addition to defining the input type for the list-contents service, RestContentListService class also overrides the transformResponse method and mandates the return value of this method to be an object of ContentPage type. This return type is same as the one used for simple-search service. ContentPage is a standard type defined in Content Integration SDK.

    The plugin must extend the implementation of list-contents service from com.hcl.unica.system.integration.service.content.list.RestContentListService class to be recognized as a valid list-contents service by the Content Integration Framework (Functional counterpart, discussed later, is also a valid choice to extend from).

    RestContentListService extends from com.hcl.unica.system.integration.service.content.list.AbstractContentListService class.

  • com.hcl.unica.system.integration.service.content.list.AbstractContentListService

    This is a common base class for RESTful as well as Functional implementations of list-contents service. So, the details covered herein applies to Functional version of list-contents as well.

    This class defines the com.hcl.unica.system.integration.service.gateway.ContentListServiceGateway interface as the service gateway for the list-contents service. This interface extends from com.hcl.unica.system.integration.service.gateway.ServiceGateway interface and mandates the ContentListRequest and ContentPage objects to be the input and output types for the list-contents service.

Get content details (get-content-details)

The following are the specialized interfaces and classes available for the get-content-details service:

  • com.hcl.unica.system.integration.service.content.details.RestContentDetailsService

    The com.aem.service.AemObjectDetailsService class in aem-integration project is a reference implementation for RESTful get-content-details service. AemObjectDetailsService class extends from RestContentDetailsService class.

    The RestContentDetailsService class has a type parameter RS, which represents the type of response (post deserialization) received from the remote REST API. In this case it is SimpleSearchResponse class defined inside the aem-integration project.

    RestContentDetailsService class implements RestService interface and defines the com.hcl.unica.system.model.request.content.details.ContentDetailsRequest class as the type argument RQ for RestService. Thus, the object of ContentDetailsRequest becomes input to all the get-content-details services (same input is used for Functional counterpart of get-content-details as well).

    In addition to defining the input type for the get-content-details service, RestContentDetailsService class also overrides the transformResponse method and mandates the return value of this method to be an object of Presentable type.

    The plugin must extend the implementation of get-content-details service from com.hcl.unica.system.integration.service.content.details.RestContentDetailsService class to be recognized as a valid get-content-details service by the Content Integration Framework (Functional counterpart, discussed later, is also a valid choice to extend from).

    RestContentDetailsService extends from the com.hcl.unica.system.integration.service.content.details.AbstractContentDetailsService class.

  • com.hcl.unica.system.integration.service.content.details.AbstractContentDetailsService

    This is a common base class for RESTful as well as Functional implementations of get-content-details service. So, the details covered herein applies to Functional version of get-content-details as well.

    This class defines the com.hcl.unica.system.integration.service.gateway.ContentDetailsServiceGateway interface as the service gateway for the get-content-details service. ServiceGateways are the means to programmatically define input and output types of the service and facilitate invocation of the services. A closer look at this interface tells us that the get-content-details service accepts the ContentDetailsRequest object and returns a Presentable object.

Get cognitive analysis (get-cognitive-analysis)

The following are the specialized interfaces and classes available for the get-cognitive-analysis service:

  • com.hcl.unica.system.integration.service.cognitive.analysis.RestCognitiveAnalysisService

    The com.example.service.rest.ExampleCognitiveAnalysisService in asset-integration-starter project is a quick starter implementation for RESTful get-cognitive-analysis service. ExampleCognitiveAnalysisService in class extends from RestCognitiveAnalysisService class.

    The RestCognitiveAnalysisService class has a type parameter RS, which represents the type of response (post deserialization) received from the remote REST API. In this case it is CognitiveDetails class defined inside the asset-integration-starter project.

    RestCognitiveAnalysisService class implements RestService interface and defines the com.hcl.unica.system.model.request.cognitive.analysis.CognitiveAnalysisRequest class as the type argument RQ for RestService. Thus, the object of CognitiveAnalysisRequest becomes input to all the get-cognitive-analysis services (same input is used for Functional counterpart as well).

    In addition to defining the input type for the get-cognitive-analysis service, RestCognitiveAnalysisService class also overrides the transformResponse method and mandates the return value of this method to be an object of com.hcl.unica.system.model.response.cognitive.analysis.CognitiveAnalysis type. CognitiveAnalysis is a standard type defined in Content Integration SDK.

    The plugin must extend the implementation of get-cognitive-analysis service from com.hcl.unica.system.integration.service.cognitive.analysis.RestCognitiveAnalysisService class to be recognized as a valid get-cognitive-analysis service by the Content Integration Framework (Functional counterpart, discussed later, is also a valid choice to extend from).

    RestCognitiveAnalysisService extends from com.hcl.unica.system.integration.service.cognitive.analysis.AbstractCognitiveAnalysisService class.

  • com.hcl.unica.system.integration.service.cognitive.analysis.AbstractCognitiveAnalysisService

    This is a common base class for RESTful as well as Functional implementations of get-cognitive-analysis service. So, the details covered herein applies to Functional version of get-cognitive-analysis as well.

    This class defines the com.hcl.unica.system.integration.service.gateway.CognitiveAnalysisServiceGateway interface as the service gateway for the get-cognitive-analysis service. This interface extends from com.hcl.unica.system.integration.service.gateway.ServiceGateway interface and mandates the CognitiveAnalysisRequest and CognitiveAnalysis objects to be the input and output types for the get-cognitive-analysis service.

Object extension service

The following are the specialized interfaces and classes available for the object extension service:
  • com.hcl.unica.system.integration.service.object.extension.RestObjectExtensionService

    The com.example.service.rest.ExampleObjectExtensionService in asset-integration-starter project is a quick starter implementation for RESTful object extension service. ExampleObjectExtensionService class extends from RestObjectExtensionService class.

    The RestObjectExtensionService class has a type parameter RS, which represents the type of response (post deserialization) received from the remote REST API. In this case, it is CognitiveDetails class defined inside the asset-integration-starter project.

    RestObjectExtensionService class implements RestService interface and defines the com.hcl.unica.system.model.request.object.extension.ObjectExtensionRequest class as the type argument RQ for RestService. Thus, the object of ObjectExtensionRequest becomes input to object extension services (same input is used for Functional counterpart as well). ObjectExtensionRequest is discussed in subsequent section.

    In addition to defining the input type for object extension service, RestObjectExtensionService class also overrides the transformResponse method and allows returning any type of object.

    The plugin must extend the implementation of object extension service from com. hcl.unica.system.integration.service.object.extension.RestObjectExtensionService class to be recognized as a valid object extension service by the Content Integration Framework (Functional counterpart, discussed later, is also a valid choice to extend from).

    RestObjectExtensionService extends from com.hcl.unica.system.integration.service.object.extension.AbstractObjectExtensionService class.

  • com.hcl.unica.system.model.request.object.extension.ObjectExtensionRequest

    The ObjectExtensionRequest provides and API to retrieve values of request attributes. The core principle of object extension service is to accept desired request attributes, perform designated operation and optionally return with a response object. Request attribute values are obtained from the object whose capabilities need to be extended by using the object extension service being implemented. Implementation of object extension service must be request object agnostic. It is the responsibility of Content Integration Framework to extract request attributes from the object to be extended and supply it to the object extension service by means of ObjectExtensionRequest. Thus, object extension service must be able to extend the capability of any object if the object being extended contains the required request attributes for the object extension service. ObjectExtensionRequest provides following methods for obtaining request attribute values –

    • Collection<AttributeValue> getAttributeValues() – This method returns a collection of all request attribute values.

      Attribute values are wrapped inside AttributeValue object, which provides API for reading the value of attribute. It provides a convenience method, as(Class<T> type), for obtaining type cast value of the attribute. Likewise, getValue() method can be used to read the uncast value.

      Furthermore, AttributeValue class provides getAttributeSchema() method to obtain the meta information about respective attribute. getAttributeSchema() returns an object of AttributeSchema containing the required meta information about attribute. The most important methods in AttributeSchema are getType() & getFormat(). These methods can be consulted to check if the attribute is of desired type. As of 12.1.1 release of Content Integration Framework, object extension service may receive values for the attributes which are not of required type. Hence, extension service must consult the type & format of the attribute before using its value. Service implementation must filter the required attribute values by itself. Refer to the buildRequest method implementation in com.example.service.rest.ExampleObjectExtensionService to learn how this can be achieved. This example implementation tries to extract first URL & first Text attribute from the request.

    • Map<String, AttributeValue> getAttributes() – Returns map of attribute values, wherein values are organized by respective attribute identifiers. This method is useful for retrieving attribute value when identifier of the desired attribute is known.

      Object extension service can override void validateRequest(ExecutionContext<ObjectExtensionRequest> executionContext) method to probe request attributes before performing core operation. InvalidServiceRequestException can be raised If desired attributes are not found in the ObjectExtensionRequest. Refer to the Validation support (link to the newly introduced Validation support further in this guide) section for more details.

  • com.hcl.unica.system.integration.service.object.extension.AbstractObjectExtensionService

    This is a common base class for RESTful as well as Functional implementations of object extension service. So, the details covered herein applies to Functional version as well.

    This class defines the com.hcl.unica.system.integration.service.gateway.ObjectExtensionServiceGateway interface as the service gateway for object extension service. This interface extends from com.hcl.unica.system.integration.service.gateway.ServiceGateway interface and mandates the ObjectExtensionRequest to be the input type for object extension service. Object extension service can return any type of object.