Derivatives of FunctionalService

Simple search (simple-search)

The following are the specialized interfaces and classes available for simple-search service:

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

  The com.example.service.functional.SimpleSearchService class in the asset-integration-starter project is a quick starter implementation for the Functional simple-search service. It extends from the com.hcl.unica.system.integration.service.search.SearchService class.

  The SearchService class implements the FunctionalService interface and defines the SearchRequest class and the ContentPage class to be the type arguments RQ & RS respectively for the FunctionalService. Thus, the object of the SearchRequest becomes an input to all the simple-search services and the ContentPage is expected as an output on completion of the service.

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

  The SearchService extends from the com.hcl.unica.system.integration.service.search.AbstractSearchService abstract class. It introduces one more method, named getSupportedContentTypes. For more information on the method, see Derivatives of RestService.

Resource loader (resource-loader)

The following are the specialized interfaces and classes available for the resource-loader service:

• com.hcl.unica.system.integration.service.resourceloader.WebResourceLoaderService
  The com.example.service.functional.ResourceLoaderService class in asset-integration-starter project is a quick starter implementation for Functional resource-loader service. It extends from the following class:

  com.hcl.unica.system.integration.service.resourceloader.WebResourceLoaderService

  The WebResourceLoaderService class implements the FunctionalService interface and defines the ResourceRequest and the HttpResponse types to be the type arguments RQ & RS, respectively, for the FunctionalService. Thus, the object of the ResourceRequest becomes an input to all the resource-loader services and the HttpResponse is expected as an output on completion of the service (the same input and output types are used for RESTful counterpart of the resource-loader). For more information on ResourceRequest & HttpResponse types, see Derivatives of RestService.

  The plugin must extend its resource-loader implementation from the com.hcl.unica.system.integration.service.resourceloader.WebResourceLoaderService service to be recognized as a resource-loader service by the Content Integration Framework (HTTP counterpart discussed in the earlier section is also a valid choice to extend from for the resource-loader services implemented using the HTTP approach).

  The WebResourceLoaderService extends from the following class:

  com.hcl.unica.system.integration.service.resourceloader.
  AbstractWebResourceLoaderService

  For more information about this class, see Derivatives of RestService.

List content categories (list-content-categories)

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

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

  Plugin can alternatively choose Functional approach to implement list-content-categories service by extending the implementation from ContentCategoriesListService class. The ContentCategoriesListService class implements the FunctionalService interface and mandates the ContentCategoryListRequest and the List<ContentCategory> classes to be the type arguments RQ and RS respectively for the FunctionalService. Thus, the object of the ContentCategoryListRequest becomes an input to the list-content-categories service and the object of List<ContentCategory> type is expected as an output on completion of the service.

• The plugin must extend its list-content-categories implementation from the com.hcl.unica.system.integration.service.content.categories.list.ContentCategoriesListService class to be recognized as a valid list-content-categories service by the Content Integration Framework (RESTful counterpart discussed in earlier section is also a valid choice to extend from).

  ContentCategoriesListService extends from AbstractContentCategoriesListService class. Details of AbstractContentCategoriesListService class are covered in the Derivatives of RestService topic.

List folders (list-folders)

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

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

  Plugin can alternatively choose Functional approach to implement list-folders service by extending the implementation from FolderListService class. The FolderListService class implements the FunctionalService interface and mandates the FolderListRequest and the List<Folder> classes to be the type arguments RQ and RS respectively for the FunctionalService. Thus, the object of the FolderListRequest becomes an input to the list-folders service and the object of List<Folder> type is expected as an output on completion of the service.

• The plugin must extend its list-folders implementation from the com.hcl.unica.system.integration.service.folder.list.FolderListService class to be recognized as a valid list-folders service by the Content Integration Framework (RESTful counterpart discussed in earlier section is also a valid choice to extend from).

  FolderListService extends from AbstractFolderListService class. Details of AbstractFolderListService class are covered in the Derivatives of RestService topic.

List contents (list-contents)

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

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

  Plugin can alternatively choose Functional approach to implement list-contents service by extending the implementation from ContentListService class. The ContentListService class implements the FunctionalService interface and mandates the ContentListRequest and the ContentPage classes to be the type arguments RQ and RS respectively for the FunctionalService. Thus, the object of the ContentListRequest becomes an input to the list-contents service and the object of ContentPage type is expected as an output on completion of the service.

• The plugin must extend its list-contents implementation from the com.hcl.unica.system.integration.service.content.list.ContentListService class to be recognized as a valid list-contents service by the Content Integration Framework (RESTful counterpart discussed in earlier section is also a valid choice to extend from).

  ContentListService extends from AbstractContentListService class. Details of AbstractContentListService class are covered in the Derivatives of RestService topic.

Get content details (get-content-details)

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

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

  Plugin can alternatively choose Functional approach to implement get-content-details service by extending the implementation from ContentDetailsService class.

  The ContentDetailsService class implements the FunctionalService interface and mandates the ContentDetailsRequest and the Presentable classes to be the type arguments RQ and RS respectively for the FunctionalService. Thus, the object of the ContentDetailsRequest becomes an input to the get-content-details service and the object of Presentable type is expected as an output on completion of the service.

  The plugin must extend its get-content-details implementation from the com.hcl.unica.system.integration.service.content.details.ContentDetailsService class to be recognized as a valid get-content-details service by the Content Integration Framework (RESTful counterpart discussed in earlier section is also a valid choice to extend from).

  ContentDetailsService extends from AbstractContentDetailsService class. Details of AbstractContentDetailsService class are covered in the Derivatives of RestService topic.

Get object schema (get-object-schema)

get-object-schema service is used to generate the master schema of domain object or entity used by the respective system to represent the content. Master schema in simplest form is just a hierarchical metadata of each mappable content attribute. Attribute hierarchy and metadata is expected to match the JSON representation of the domain object. Attribute metadata mainly includes the data type of the attribute, format of the value held in the attribute, unique identifier of the attribute and display title or label for the attribute.

The following are the specialized interfaces and classes available for get-object-schema service:

• com.hcl.unica.system.integration.service.object.schema.ObjectSchemaProviderService

  The ObjectSchemaProviderService class implements the FunctionalService interface and mandates the com.hcl.unica.system.model.ObjectSchemaRequest and the com.hcl.unica.system.model.json.schema.ObjectSchema classes to be the type arguments RQ and RS respectively for the FunctionalService. Thus, the object of the ObjectSchemaRequest becomes an input to the get-object-schema service and the object of ObjectSchema type is expected as an output on completion of the service. Plugin however need not build the ObjectSchema by itself. It should just override and implement following abstract method from ObjectSchemaProviderService class.

  ObjectProfile getObjectProfile(ObjectSchemaRequest objectSchemaRequest)

  The getObjectProfile() method accepts ObjectSchemaRequest and returns ObjectProfile. (These types are discussed in subsequent section.)

  The plugin must extend get-object-schema implementation from the com.hcl.unica.system.integration.service.object.schema.ObjectSchemaProviderService class to be recognized as a valid get-object-schema service by the Content Integration Framework. There is no RESTful counterpart of this standard super class since object schema generation does not include any HTTP interaction. Plugins can implement custom RESTful service and invoke it internally from within get-object-schema service if required.

• com.hcl.unica.system.model.ObjectSchemaRequest

  Object of this class is supplied as an input to the get-object-schema service. The most important method of this class is getObjectIdentity() which returns an object of type com.hcl.unica.system.model.ObjectIdentity encapsulating the details of the content chosen by the user to request the master schema. It includes applicationId (the system identifier), objectType (content type/category identifier) and objectId (unique identifier of the selected content). Regardless of the category and/or content chosen by the user at the time of setting up content mapping, the generated schema must include attributes of all kinds of contents supported by the respective system. In other words, only one master schema is used for mapping all types of contents provided by the given system.

  The getEnrichmentObjectJson() method in ObjectSchemaRequest class can be ignored as of current release.

• com.hcl.unica.system.integration.service.object.schema.ObjectProfile

  This is a return type of getObjectProfile() method in get-object-schema service. It carries the Java type corresponding to the domain entity/object for the respective system. Content Integration Framework consults this Java type to generate the schema for public and non-public non static class properties (inclusive of Enums & Optionals). @MappableAttribute annotation can be used to configure each individual class property to control the schema generated by Content Integration Framework. Refer to the com.aem.model.response.simplesearch.SimpleSearchItem domain object in aem-integration reference project to get an idea about how this annotation is used. More details are provided on @MappableAttribute in next section. ObjectProfile can optionally include an instance of com.hcl.unica.system.integration.service.object.schema.ObjectSchemaEnricher to dynamically add/modify/remove attributes from the schema thus generated. Next section explains ObjectSchemaEnricher in detail.

• com.hcl.unica.system.integration.service.object.schema.ObjectSchemaEnricher

  ObjectSchemaEnricher is an abstract class. Plugin should extend it to have desired implementation. The type parameter to ObjectSchemaEnricher class represents the Java type containing the additional details required for enriching the statically generated object schema. These additional details might be provided by the client applications of Unica Content Integration. As of current release, no additional details are provided, hence it should be set to Void while implementing the schema enricher. ObjectSchemaEnricher declares only one abstract method which should be implemented by the plugin:

  abstract public ObjectSchema enrich(
  		ObjectSchema objectSchema, 
  		ObjectSchemaEnrichmentRequest<T> objectSchemaEnrichmentRequest
  )

  The first argument to this method is an instance of com.hcl.unica.system.model.json.schema.ObjectSchema class. It contains the automatically generated domain object schema derived from the Java type supplied in ObjectProfile. At its core, ObjectSchema is just a Map<String, AttributeSchema>, wherein class property names forms the keys of this map and property metadata ends up as an object of AttributeSchema. If the class property in turn refers to another object, the corresponding AttributeSchema will have another Map<String, AttributeSchema> containing the attributes of that object type and so on.

  Note: It is important to note that attribute names used as the keys in attribute map correspond to the JSON properties which ends up in the JSON representation of the domain object. Hence, if @JsonProperty annotation is used to override the JSON property name for certain class attribute, then Content Integration Framework automatically detects it and use the overridden property name.

  ObjectSchema as well as AttributeSchema extend from com.hcl.unica.system.model.json.schema.AttributeContainer abstract class. AttributeContainer provides convenience methods to ObjectSchema and AttributeSchema classes for navigating through attribute hierarchy as well as for adding, modifying and removing attributes at any level in the hierarchy to ease the schema enrichment. Attributes at any level in the hierarchy can be accessed and manipulated using their names as appearing in JSON representation.

• com.hcl.unica.system.model.json.schema.generator.annotations.MappableAttribute

  @MappableAttribute annotation provides a way to control how Content Integration Framework generates object schema from the respective Java type. Use of @MappableAttribute is not mandatory. If it is not used, Content Integration Framework automatically figures out property metadata. If required, this annotation should be placed on top of desired class properties. Following annotation attributes can be used to control the schema generation:

  • hidden – Set this to true to explicitly exclude certain property from object schema (@JsonIgnore is presently not considered by Content Integration Framework. Hence, any property excluded from JSON representation using @JsonIgnore must be explicitly excluded from schema)
  • id – Supply unique identifier for the property. Content Integration Framework needs unique identifier for each mappable class property. If @MappableAttribute is not used, or id is not specified, it generates one automatically based on the location of property inside the class.

    Automatic generation of attribute identifier is subject to the name and the hierarchical location of class property inside the domain object graph. It implies that if the property name is changed and/or moved up or down the object graph hierarchy, it will change the identifier associated with it. Such refactoring can mislead Content Integration Framework while reading the values of refactored attributes and may lead to undesired data in mapped contents (such as Offers in COM). Hence, to avoid such inadvertent changes in attribute identifiers, we recommend you to assign unique attribute identifiers manually, which remain constant regardless of the name and location of class properties.

  • title – Display title/label for the property. If omitted, Content Integration Framework generates one using property name.
  • type – One of the values from com.hcl.unica.system.model.json.schema.generator.annotations.AttributeType. If omitted, Content Integration Framework automatically figures out the appropriate type.
  • format – One of the values from com.hcl.unica.system.model.json.schema.generator.annotations.AttributeFormat. Content Integration Framework can automatically identify standard java temporal types (Date, LocalDateTime, Instant) and set the attribute type to DATETIME. Other formats should be explicitly declared.
  • implementation – Should be used for polymorphic references to explicitly declare the Java type to be considered for automatic schema generation.
  • hiddenProperties - @MappableAttribute annotation can be used at the class level to hide multiple properties at single place. hiddenProperties takes an array of Strings containing the names of properties (direct as well as inherited ones) to be excluded from automatically generated schema. It is particularly useful for hiding properties inherited from third party parent class.

  Java Type to AttributeType Mapping

  Following table summarizes the mapping between Java type and AttributeType/AttributeFormat used by the Content Integration Framework for automatic schema generation:

  Java Type	AttributeType	AttributeFormat
  String Character Char CharSequence LocalDate LocalTime ZonedDateTime OffsetDateTime OffsetTime ZoneId Calendar UUID	STRING
  Boolean boolean	BOOLEAN
  BigInteger Integer Int Long Long Short Short Byte byte	INTEGER
  BigDecimal Number Double Double Float float	NUMBER
  Date LocalDateTime Instant Content Integration Framework expects date values be expressed in UTC standard time. Temporal values expressed in any other timezone can lead to inaccurate temporal calculations in further use cases.	INTEGER	DATETIME

Get cognitive analysis (get-cognitive-analysis)

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

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

  Plugin can alternatively choose Functional approach to implement get-cognitive-analysis service by extending the implementation from CognitiveAnalysisService class. The CognitiveAnalysisService class implements the FunctionalService interface and mandates the CognitiveAnalysisRequest and the CognitiveAnalysis classes to be the type arguments RQ and RS respectively for the FunctionalService. Thus, the object of the CognitiveAnalysisRequest becomes an input to the get-cognitive-analysis service and the object of CognitiveAnalysis type is expected as an output on completion of the service.

• The plugin must extend its get-cognitive-analysis implementation from the com.hcl.unica.system.integration.service.cognitive.analysis.CognitiveAnalysisService class to be recognized as a valid get-cognitive-analysis service by the Content Integration Framework (RESTful counterpart discussed in earlier section is also a valid choice to extend from).

  CognitiveAnalysisService extends from AbstractCognitiveAnalysisService class. Details of AbstractCognitiveAnalysisService class are covered in the Derivatives of RestService topic.