Server-side Customization

⇐ Feature Essentials Client-side Customization ⇒
SCF Handlebars Helpers ⇒

Java APIs

NOTE

The package location of Communities APIs is subject to change when upgrading from one major release to the next.

SocialComponent Interface

SocialComponents are POJOs that represent a resource for an AEM Communities feature. Ideally, each SocialComponent represents a specific resourceType with exposed GETters that provide data to the client so the resource is accurately represented. All business logic and view logic is encapsulated in the SocialComponent, including the site visitor’s session information, if necessary.

The interface defines a basic set of GETters that are necessary to represent a resource. Importantly, the interface stipulates Map<String, Object> getAsMap() and String toJSONString() methods that are necessary in order to render Handlebars templates and expose GET JSON endpoints for resources.

All SocialComponent classes must implement the interface com.adobe.cq.social.scf.SocialComponent

SocialCollectionComponent Interface

The SocialCollectionComponent interface extends the SocialComponent interface to better represent resources that are collections of other resources.

All SocialCollectionComponent classes must implement the interface com.adobe.cq.social.scf.SocialCollectionComponent

SocialComponentFactory Interface

A SocialComponentFactory (factory) registers a SocialComponent with the framework. The factory provides a means of letting the framework know what SocialComponents are available for a given resourceType and their priority ranking* when multiple SocialComponents are identified.

A SocialComponentFactory is responsible for creating an instance of the selected SocialComponent making it possible to inject all dependencies needed by the SocialComponent from the factory using DI practices.

A SocialComponentFactory is an OSGi service and has access to other OSGi services which can be passed to the SocialComponent through a constructor.

All SocialComponentFactory classes must implement the interface com.adobe.cq.social.scf.SocialComponentFactory

An implementation of SocialComponentFactory.getPriority() method should return the highest value in order for the factory to be used for the given resourceType as returned by getResourceType().

SocialComponentFactoryManager Interface

The SocialComponentFactoryManager (manager) manages all SocialComponents registered with the framework and is responsible for selecting the SocialComponentFactory to use for a given resource (resourceType). If no factories are registered for a specific resourceType, the manager will return a factory with the nearest super type for the given resource.

A SocialComponentFactoryManager is an OSGi service and has access to other OSGi services which can be passed to the SocialComponent through a constructor.

A handle to the OSGi service is obtained by invoking com.adobe.cq.social.scf.SocialComponentFactoryManager

HTTP API - POST Requests

PostOperation Class

The HTTP API POST endpoints are PostOperation classes defined by implementing the SlingPostOperationinterface (package org.apache.sling.servlets.post).

The PostOperationendpont implementation sets sling.post.operationto a value to which the operation will respond. All POST requests with an:operation parameter set to that value will be delegated to this implementation class.

The PostOperationinvokes the SocialOperationwhich performs the actions necessary for the operation.

The PostOperationreceives the result from the SocialOperationand returns the appropriate response to the client.

SocialOperation Class

Each SocialOperationendpoint extends the AbstractSocialOperation class and overrides the method performOperation().This method performs all actions needed to complete the operation and return a SocialOperationResultor else throw an OperationException, in which case an HTTP error status with a message, if available, is returned in place of the normal JSON response or success HTTP status code.

Extending AbstractSocialOperationmakes possible the reuse of SocialComponentsto send JSON responses.

SocialOperationResult Class

The SocialOperationResultclass is returned as the result of the SocialOperationand is composed of a SocialComponent, HTTP status code, and HTTP status message.

The SocialComponentrepresents the resource that was affected by the operation.

For a Create operation, the SocialComponentincluded in the SocialOperationResultrepresents the resource just created and for an Update operation, it represents the resource that was altered by the operation. No SocialComponentis returned for a Delete operation.

The success HTTP status codes used are

  • 201 for Create operations
  • 200 for Update operations
  • 204 for Delete operations

OperationException Class

An OperationExceptoncan be thrown when performing an operation if the request is not valid or some other error occurs, such as internal errors, bad parameter values, improper permissions, etc. An OperationExceptionis composed of an HTTP status code and an error message, which are returned to the client as the response to the PostOperatoin.

OperationService Class

The social component framework recommends that the business logic responsible for performing the operation not be implemented within the SocialOperationclass, but instead delegated to an OSGi service. Using an OSGi service for business logic allows a SocialComponent, acted upon by a SocialOperationendpoint, to be integrated with other code and have different business logic applied.

All OperationServiceclasses extend AbstractOperationService, allowing additional extensions which can hook into the operation being performed. Each operation in the service is represented by a SocialOperationclass. The OperationExtensionsclass can be invoked during operation execution by calling the methods

  • performBeforeActions()
    Allows for pre-checks/pre-processing and validations
  • performAfterActions()
    Allows for further modification of resources or invoking custom events, workflows, etc

OperationExtension Class

OperationExtensionclasses are custom pieces of code that can be injected into an operation allowing for customization of operations to meet business needs. The consumers of the component can dynamically and incrementally add functionality to the component. The extension/hook pattern allows developers to focus exclusively on the extensions themselves and removes the need for copying and overriding entire operations and components.

Sample Code

Sample code is available in the Adobe Marketing Cloud GitHub repository. Search for projects prefixed with either aem-communities or aem-scf.

Best Practices

View the Coding Guidelines section for various coding guidelines and best practices for AEM Communities developers.

See also Storage Resource Provider (SRP) for UGC to learn about accessing user generated content.

⇐ Feature Essentials Client-side Customization ⇒
SCF Handlebars Helpers ⇒

On this page