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

  Collection<String> is resolved as comma separated list of strings. If any string element in the collection contains comma, it is enclosed in double quotes. If the enclosed string contains any double quote of its own, then its double quote is escaped by another double quote.

  For example, a list of strings like [“string 1”,”string 2”,”string, 3”,”string,\”4”,”string\”5”] is resolved as follows –

  string 1,string 2,”string, 3”,”string,””4”,string”5

  Notice that string”5 is not enclosed in double quotes since it does not contain any comma.

• com.hcl.unica.system.model.Mappable

  Contents from content repositories are linked to Unica objects using content URLs. Once any content URL is referenced inside Unica objects, Content Integration Framework allows showing preview of already linked content by making use of get-content-details service. To achieve such content previews at later point of time, Content Integration Framework & Unica products store the system identifier, category/type & identifier of the linked content. By default, any attribute declared as AttributeType.STRING & AttributeFormat.URL using @MappableAttribute annotation will be considered as an URL belonging to the main content. If such URL attribute value is referenced in Unica objects, then the preview for such reference will show the details of content it belongs to. However, the URL attribute may not necessarily represent the content object it is wrapped in. It may be a separate entity managed inside target content repository. For example, a Book object may include two different image URL attributes, called bookCover & authorPhoto. While preview for bookCover should certainly show the details of the book it represents, authorPhoto however should show the brief bio about book’s author.

  With the default arrangement, Content Integration Framework continues to show the book details for authorPhoto’s preview unless explicitly overridden by the plugin. The Mappable interface provides an opportunity to override this default behavior for desired attribute. To override the content preview for any attribute, domain class must implement the Mappable interface and override following method –

  ObjectIdentity overrideObjectReference(String attributeId, ObjectIdentity defaultReference)

  The overrideObjectReference method accepts the attribute identifier whose real content identity needs to be established. It also receives the default identity assumed by Content Integration Framework as second argument. Plugin can conditionally override the content identity by matching the attributeId with desired attribute’s identifier. The ObjectIdentity returned from this method essentially tells the real system (applicationId), category (objectType) & identifier (objectId) of the respective attribute. Returning null from this method turns the content preview off. In other circumstances, plugin should respond with defaultReference value to let the Content Integration Framework function normally.

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.

Object extension service

The following are the specialized interfaces and classes available for object extension service:

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

  Plugin can alternatively choose Functional approach to implement object extension service by extending the implementation from ObjectExtensionService class. The ObjectExtensionService class implements the FunctionalService interface and mandates the ObjectExtensionRequest and the Object classes to be the type arguments RQ and RS respectively for the FunctionalService. Thus, the object of the ObjectExtensionRequest becomes an input to the object extension service and expects any type of as an output on completion of the service.

  ObjectExtensionRequest is covered in more detail under RESTful section of object extension service.

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

  ObjectExtensionService extends from AbstractObjectExtensionService class. Details of AbstractObjectExtensionService class are covered in the Derivatives of RestService topic.