com.endeca.infront.assembler
Interface CartridgeHandler<T extends ContentItem>

Type Parameters:

T - The sub-type of ContentItem that this cartridge handles

All Known Implementing Classes:

AbstractCartridgeHandler, BreadcrumbsHandler, ContentIncludeHandler, ContentSlotHandler, ContentSlotListHandler, DimensionSearchResultsHandler, MediaBannerHandler, NavigationCartridgeHandler, NavigationContainerHandler, RecordDetailsHandler, RecordSpotlightHandler, RedirectAwareContentIncludeHandler, RefinementMenuHandler, ResultsListHandler, SearchAdjustmentsHandler, StatsPageCartridgeHandler

public interface CartridgeHandler<T extends ContentItem>

An interface for inserting custom cartridge logic into the assembler. Cartridge handlers are invoked by the assembler based upon cartridge type.

Resolving Cartridge Handlers

Assembler implementations resolve cartridge handlers based upon cartridge types, which are equivalent to Experience Manager template IDs. Assembler implementations resolve cartridge handlers once per cartridge instance during an assembly cycle.

In the case that no cartridge handler is found for a given cartridge type, the default behavior of the assembler is to simply return the content data from Experience Manager.

Processing Cycle

Assembler implementations process each cartridge in two phases:

1. initialize(ContentItem) and preprocess(ContentItem)
2. process(ContentItem)

In the first phase, the assembler first invokes the initialize(ContentItem) method for each cartridge instance. This method allows cartridge handlers to return an instance of ContentItem with all configuration initialization complete. The cartridge handler may choose to return the same, possibly mutated, instance that it received as an input argument, or it may return a new instance of ContentItem. The ContentItem instance returned by initialize will be passed as the input argument to both preprocess(ContentItem) and process(ContentItem). Immediately after invoking the initialize method, the assembler then invokes the preprocess method for each cartridge instance.

Once the preprocess method has been invoked on each cartridge instance (completing the preprocess traversal), the assembler invokes the process method for each cartridge instance. The implementation may keep state between the call to preprocess and the call to process.

Example Cartridge Handler

Here is a simple cartridge handler that uppercases a 'message' property from Experience Manager. Since this handler does not require initialization of the ContentItem or any preparation in preprocess, it extends AbstractCartridgeHandler, which provides a no-op implementation of both methods.

 public class UppercaseCartridgeHandler extends AbstractCartridgeHandler
 {
   //====================================================================
   // The cartridge handler 'process' method
   public ContentItem process(ContentItem pContentItem) throws CartridgeHandlerException
   {
     // Get the message property off of the content item.
     final String message = (String) pContentItem.get("message");
     // If the message is non-null, uppercase it.
     if (null != message) {
        pContentItem.put("message", message.toUpperCase());
     }
     return pContentItem;
   }
 }
 

Method Summary

T	initialize(ContentItem pContentItem) Called by the assembler once for each cartridge instance, immediately before preprocess(ContentItem) is called.
void	preprocess(T pContentItem) Called by the assembler once for each cartridge instance in a response model.
ContentItem	process(T pContentItem) Called by the assembler after the preprocess method has been called for all cartridges in a complete response model.

Method Detail

initialize

T initialize(ContentItem pContentItem)
                                 throws CartridgeHandlerException

Called by the assembler once for each cartridge instance, immediately before preprocess(ContentItem) is called. This method allows handlers to add default configuration information to the supplied cartridge instance configuration, typically from Experience Manager. It also allows handlers to wrap the ContentItem with a sub-classed version that provides appropriate getters and setters.

The return value from this method will be passed as the input argument to preprocess(ContentItem) and process(ContentItem).

Parameters:

pContentItem - cartridge instance configuration, typically from Experience Manager.

Returns:

a fully initialized instance of ContentItem. This instance will replace the input instance in the assembler's reference tree, and it will be passed as the input to both preprocess and process. If null is returned, preprocess and process will not be called and an exception will be packaged in the overall response model. Returning null will not halt the entire assembly process, which occurs across multiple cartridges.

Throws:

CartridgeHandlerException - if an error occurs that is scoped to an individual cartridge instance (for instance, the handler is unable to access its default configuration). This exception will not halt the entire assembly process, which occurs across multiple cartridges; instead, this exception will be packaged in the overall response model. If an unchecked exception is thrown, then the entire assembly process will be halted.

preprocess

void preprocess(T pContentItem)
                throws CartridgeHandlerException

Called by the assembler once for each cartridge instance in a response model. The assembler uses a pre-order traversal pattern, so it is appropriate to modify the given ContentItem in this phase.

Parameters:

pContentItem - the cartridge configuration returned by initialize(ContentItem). This cartridge configuration may be modified by this handler. Note that this cartridge configuration is also passed to process(ContentItem).

Throws:

CartridgeHandlerException - if an error occurs that is scoped to an individual cartridge instance. This exception will not halt the entire assembly process, which occurs across multiple cartridges; instead, this exception will be packaged in the overall response model. If an unchecked exception is thrown, then the entire assembly process will be halted.

process

ContentItem process(T pContentItem)
                    throws CartridgeHandlerException

Called by the assembler after the preprocess method has been called for all cartridges in a complete response model. The assembler uses a post-order traversal pattern, so all children should be processed by the time this method is called.

If a CartridgeHandlerException is thrown during the preprocess method, then the process method is not called.

Parameters:

pContentItem - the cartridge configuration returned by initialize(ContentItem). Note that this instance may have been modified by the preprocess(ContentItem) method.

Returns:

the output value for this cartridge. If null is returned, then the corresponding node in the output tree will be deleted.

Throws:

CartridgeHandlerException - if an error occurs that is scoped to an individual cartridge instance. This exception will not halt the entire assembly process, which occurs across multiple cartridges; instead, this exception will be packaged in the overall response model. If an unchecked exception is thrown, then the entire assembly process will be halted.