The Assembler is an Oracle Commerce component that performs the following essential roles in any Oracle Commerce application:
It acts as the runtime component of Experience Manager, a tool that enables the business user to configure the runtime appearance and behavior of the application.
It accesses values from a variety of sources, including databases, Digital Asset Management systems, social media feeds, and the MDEX engine.
It creates view-ready application component models known as cartridges. A cartridge is a series of key and value pairs known as a content item. The key and value pairs contain values accessed by the Assembler. Your application renders these values visually, in the UI controls or other components that compose the pages in your application.
Note
Some content items contain other content items rather than consumer information. These content items represent different types of content and together form a hierarchical tree that can be traversed by the application when rendering a page.
The Assembler classes are organized into two Java libraries:
Assembler Core, packaged as
endeca_assembler_core-<version>.jar. This library provides the core Assembler interfaces and a Spring implementation of the Assembler, along with the core facilities for building Experience Manager driven applications.Assembler Navigation, packaged as
endeca_assembler_navigation-<version>.jar. This library provides the built-in cartridges and facilities for building applications with Search and Guided Navigation.A separate javadoc is provided for each JAR file.
The following diagram illustrates the role of the Assembler in an Oracle Commerce implementation:
As shown in the preceding diagram, the following things happen when customers request information through your application page:
Your application invokes the
assemble()method as follows:ContentItem contentItem = new RedirectAwareContentInclude("/myUrl");ContentItem responseContentItem = assembler.assemble(contentItem)where
/myUrlis the URL to a page that you are assembling in Experience Manager andresponseContentItemis a tree of other content items.The
assemble()method sendsresponseContentItemto the Assembler.The Assembler passes the individual content items in
responseContentItemto cartridge handlers, each of which handles a different content type. Each content item specifies a request for information.The cartridge handlers pass the requests on to the appropriate sources of information, such as an MDEX Engine, a relational database system, a content management system, and so on.
The cartridge handlers receive and process information from their respective sources. The handlers contain all the logic needed to process the information, though they may also process requests without requiring input from an external data source.
Each cartridge handler returns to the Assembler a content item that contains the requested information.
The Assembler combines the content items that it receives from all of the cartridge handlers into a
responseContentItem, which is structured as a tree that contains all of the information required by the front end application.The Assembler returns
responseContentItemto the front end application.Rendering code in the application converts the information in
responseContentIteminto a form that can be displayed in the appropriate cartridges on your application page. Typically, a cartridge renderer (a separate module of rendering code) processes and displays the information for each content item in theresponseContentItemtree.Note
The Assembler can return XML or JSON representations of objects for consumption by a variety of rendering engines, such as .NET, PHP, or Flash-based applications. It can also return model objects as POJOs (plain old Java objects) when embedded in a native Java application.
The Tools and Frameworks package includes a Java Assembler implementation that uses Spring to resolve cartridge handlers and services.
You can develop extensions to the framework to interact with your resources, centralizing runtime data retrieval and manipulation in your application. For these reasons, the Assembler can be integrated with organizations that use Service-Oriented Architecture.
The Assembler
stores and manipulates data as sets of
key:value pairs known as content items. Content items can
represent cartridges, which map to front-end features in an application.
Some content items are structural components such as application pages that contain additional content items. Other content items map to front-end components in an application, such as image banners.
For example, in the Discover Electronics reference implementation, the entire default "browse" page is represented by a content item that contains the page template. Each section of the page is also a content item, nested within the containing "three column page" content item. Within those sections are additional content items that represent front-end features:
Because the content items are organized as a tree, they are as a group easy to traverse for rendering.
A cartridge is a content item with a specific role in your application; for example, a cartridge can map to a GUI component in the front-end application. The Assembler includes a number of cartridges that map to typical GUI components – for example, a Breadcrumbs cartridge, a Search Box cartridge, and a Results List cartridge. You can create other cartridges that map to other GUI components expected by your business users.
Every cartridge is defined by a template. A cartridge template defines:
Experience Manager instantiates each content item from its cartridge template. This includes any configuration made by the business user, and results in a content item with instance configuration that is passed to the Assembler.
A cartridge handler takes a content item as input, processes it, and returns a content item as output.
The input content item typically includes instance configuration, which consists of any properties specified by a business user using Experience Manager in Workbench. The content item is typically initialized by layering configuration from other sources: your application may include default values, or URL parameters that represent end user selections in the front-end application.
A cartridge handler can optionally perform further processing, such as querying a search engine for data. When processing is finished, the handler returns a completed content item to the application.
Note
Not all cartridges require cartridge handlers. In the case of a content item with no associated cartridge handler, the Assembler returns the unmodified content item.
For detailed information regarding the
CartridgeHandler interface, see
About the CartridgeHandler interface,
or refer to the
Assembler API Reference (Javadoc).
Consider
the Results List cartridge included with Tools and Frameworks in the Assembler
Navigation JAR file. The
ResultsList object that backs the cartridge is a
content item. The ResultsList cartridge template exposes a subset of object
properties for configuration in Experience Manager. The remaining properties
are configurable through the UI in the front-end application.
The Results List cartridge handler combines the default, instance, and
URL configuration values to create a query to send to the MDEX Engine. The
values in the query response are used to populate the
ResultsList content item and return it to the
application for rendering.
