atg.commerce.catalog.restresources

Class CategoryRestResource

java.lang.Object

atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

atg.nucleus.GenericService

atg.service.jaxrs.restresources.AbstractItemLookupRestResource

atg.commerce.catalog.restresources.AbstractCatalogRestResource

atg.commerce.catalog.restresources.CategoryRestResource

All Implemented Interfaces:

atg.core.logging.Logging, atg.core.logging.TraceLogging, atg.naming.AbsoluteNameable, NameContextBindingListener, NameContextElement, atg.naming.NameContextParentable, NameResolver, AdminableService, atg.nucleus.Configured, ApplicationLogging, atg.nucleus.logging.ApplicationLoggingSender, atg.nucleus.logging.TraceApplicationLogging, VariableArgumentApplicationLogging, ComponentNameResolver, Service, ServiceListener, java.util.EventListener

@RestResource(id="atg.commerce.catalog.restresources.CategoryRestResource")
public class CategoryRestResource
extends AbstractCatalogRestResource

This class provides the category's RESTful endpoints, exposing category data.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CLASS_VERSION Class version string
static java.lang.String	COLLECTION_ALL_CATS_NO_CATALOG_SET
static java.lang.String	ROOT_CATEGORIES

Fields inherited from class atg.service.jaxrs.restresources.AbstractItemLookupRestResource

COLLECTION_MISSING_INPUT_PARAMS, COLLECTION_PARENT_ITEM_NOT_FOUND, COLLECTION_PARENT_REPOSITORY_NOT_FOUND, COLLECTION_PROPERTY_INVALID, COLLECTION_PROPERTY_NOT_FOUND, COLLECTION_SORT_SIZE, COMMA, DEFAULT_PAGE_SIZE, ID, INVALID_QUERY_PARAMS, ITEM, ITEM_DESCRIPTOR_NOT_SUPPLIED, ITEM_NOT_FOUND, mEmbeddedRelationshipToResourceId, mRepository, PARENT_ITEM_ID, PARENT_ITEM_TYPE, PARENT_PROPERTY_NAME, REQUEST_DATA_KEY_PREFIX, RESOURCE_NAME, SEPARATOR, sResourceBundle, UNEXPECTED_ERROR

Fields inherited from class atg.nucleus.GenericService

SERVICE_INFO_KEY

Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging

DEFAULT_LOG_TRACE_STATUS

Fields inherited from interface atg.nucleus.logging.ApplicationLogging

DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS

Constructor Summary

Constructors

Constructor and Description
CategoryRestResource()

Method Summary

Modifier and Type	Method and Description
java.lang.String	getCatalogRootCategoriesProperty() Return catalog's top-level category ids property name, defaults to allRootCategories
RepresentationModel	getCategory(java.lang.String pCategoryId, java.lang.Boolean pFilterByCatalogFlag, java.lang.Boolean pFilterBySiteFlag, java.lang.String pSiteId) Returns a representation of a category for the given category id.
java.lang.String	getChildCategoriesRelationshipName() Return the relationship name to the embedded categories resource for childCategories.
java.lang.String	getChildProductsRelationshipName() Return the relationship name to the embedded products resource for childProducts.
java.lang.String	getParentCategoryRelationshipName() Return the relationship name to the embedded category resource for parentCategory
java.lang.String	getRelatedCategoriesRelationshipName() Return the relationship name to the embedded categories resource for relatedCategories.
protected RepresentationModel.Builder	getRepresentationModelBuilder(java.lang.Object pState) Gets the RepresentationModel.Builder with the given object acting as the state.
RepresentationModel	listCategories(java.lang.String pParentItemId, java.lang.String pParentItemType, java.lang.String pParentPropertyName, java.lang.String pOffset, java.lang.String pLimit, java.lang.String pOrderBy) Gets a list of categories.
void	setCatalogRootCategoriesProperty(java.lang.String pCatalogRootCategoriesProperty) Configure the catalog's top-level categories property name for displaying the top-level categories collection.
void	setChildCategoriesRelationshipName(java.lang.String pChildCategoriesRelationshipName) Configure the childCategories relationship name to the categories resource (collection).
void	setChildProductsRelationshipName(java.lang.String pChildProductsRelationshipName) Configure the childProducts relationship name to the product collection resource.
void	setParentCategoryRelationshipName(java.lang.String pParentCategoryRelationshipName) Configure the parentCategory relationship name to the category resource (singular).
void	setRelatedCategoriesRelationshipName(java.lang.String pRelatedCategoriesRelationshipName) Configure the relatedCategoriess relationship name to the categories resource (collection).

Methods inherited from class atg.commerce.catalog.restresources.AbstractCatalogRestResource

buildInputs, embedParentCategory, getCatalogTools, getItem, postInvoker, preInvoker, retrieveItem, setCatalogTools

Methods inherited from class atg.service.jaxrs.restresources.AbstractItemLookupRestResource

addEmbeddedCollectionResource, addEmbeddedCollectionResources, buildInputs, generateRequestDataKey, getCollectionSortLimit, getDefaultLimit, getDroplet, getEmbeddedRelationshipToResourceId, getItem, getItemDescriptor, getParentRepositoryItem, getRepository, listItems, listItems, listItems, retrieveRequestData, setCollectionSortLimit, setDefaultLimit, setDroplet, setEmbeddedRelationshipToResourceId, setItemDescriptor, setRepository, validateProperty

Methods inherited from class atg.nucleus.GenericService

addLogListener, createAdminServlet, doStartService, doStopService, getAbsoluteName, getAdminServlet, getAdminServletOutputStreamEncoding, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isAdminServletUseServletOutputStream, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, reResolveThis, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setAdminServletOutputStreamEncoding, setAdminServletUseServletOutputStream, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService, toString

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogDebugTrace, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

CLASS_VERSION

public static final java.lang.String CLASS_VERSION

Class version string

See Also:

Constant Field Values

ROOT_CATEGORIES

public static final java.lang.String ROOT_CATEGORIES

See Also:

Constant Field Values

COLLECTION_ALL_CATS_NO_CATALOG_SET

public static final java.lang.String COLLECTION_ALL_CATS_NO_CATALOG_SET

See Also:

Constant Field Values

Constructor Detail

CategoryRestResource

public CategoryRestResource()

Method Detail

setCatalogRootCategoriesProperty

public void setCatalogRootCategoriesProperty(java.lang.String pCatalogRootCategoriesProperty)

Configure the catalog's top-level categories property name for displaying the top-level categories collection. Property is expected to be a set of category items.

Parameters:

pCatalogRootCategoriesProperty - the name of the catalog's top-level categories

getCatalogRootCategoriesProperty

public java.lang.String getCatalogRootCategoriesProperty()

Return catalog's top-level category ids property name, defaults to allRootCategories

Returns:

the name of the catalog's top-level category ids property

setChildCategoriesRelationshipName

public void setChildCategoriesRelationshipName(java.lang.String pChildCategoriesRelationshipName)

Configure the childCategories relationship name to the categories resource (collection). The name is output in the (json) response. If re-configured any current filter configuration embedded references will need updated to reflect the change.

Parameters:

pChildCategoriesRelationshipName - the relationship name of the embedded category resource

getChildCategoriesRelationshipName

public java.lang.String getChildCategoriesRelationshipName()

Return the relationship name to the embedded categories resource for childCategories. Allows the json name to be changed. Defaults to the configured setting i.e. the repository name.

Returns:

the relationship name of the embedded category resource

setRelatedCategoriesRelationshipName

public void setRelatedCategoriesRelationshipName(java.lang.String pRelatedCategoriesRelationshipName)

Configure the relatedCategoriess relationship name to the categories resource (collection). The name is output in the (json) response. If re-configured any current filter configuration embedded references will need updated to reflect the change.

Parameters:

pRelatedCategoriesRelationshipName - the relationship name of the embedded product resource

getRelatedCategoriesRelationshipName

public java.lang.String getRelatedCategoriesRelationshipName()

Return the relationship name to the embedded categories resource for relatedCategories. Allows the json name to be changed. Defaults to the repository name, as defined in CatalogProperties.

Returns:

the relationship name of the embedded resource

setChildProductsRelationshipName

public void setChildProductsRelationshipName(java.lang.String pChildProductsRelationshipName)

Configure the childProducts relationship name to the product collection resource. The name is output in the (json) response. If re-configured any current filter configuration embedded references will need updated to reflect the change.

Parameters:

pChildProductsRelationshipName - the relationship name of the embedded product resource

getChildProductsRelationshipName

public java.lang.String getChildProductsRelationshipName()

Return the relationship name to the embedded products resource for childProducts. Allows the json name to be changed. Defaults to the configured setting i.e. the repository name.

Returns:

the relationship name of the embedded product resource

setParentCategoryRelationshipName

public void setParentCategoryRelationshipName(java.lang.String pParentCategoryRelationshipName)

Configure the parentCategory relationship name to the category resource (singular). The name is output in the (json) response. If re-configured any current filter configuration embedded references will need updated to reflect the change.

Parameters:

pParentCategoryRelationshipName - the relationship name of the embedded category resource

getParentCategoryRelationshipName

public java.lang.String getParentCategoryRelationshipName()

Return the relationship name to the embedded category resource for parentCategory

Returns:

the relationship name of the embedded category resource

listCategories

@Endpoint(id="/categories#GET",
          filterId="categories-Default")
public RepresentationModel listCategories(java.lang.String pParentItemId,
                                                                                                                   java.lang.String pParentItemType,
                                                                                                                   java.lang.String pParentPropertyName,
                                                                                                                   java.lang.String pOffset,
                                                                                                                   java.lang.String pLimit,
                                                                                                                   java.lang.String pOrderBy)
                                                                                                            throws RestException,
                                                                                                                   RepositoryException,
                                                                                                                   javax.servlet.ServletException

Gets a list of categories.

Can be used to get the top-level set of categories for the current user's catalog. This is the default behaviour if no params are passed.

Or can be used to retrieve the child product collection of a repository item. The parent item's property name referencing the child collection, alongside the id & item type identifying the parent item are passed as query parameters.

This top-level collection resource can be embedded in resources, for example the category's relatedCategories. When embedded we support the parent item object being passed via the request data map for performance. The property name along with the item passed will be used to identify the collection.

This collection may be large, therefore it will be paged to return a manageable set of data. Paging can be controlled using the REST-Jersey framework's pagination-supported query parameter, offset & limit. If no limit (i.e.page size) is set the defaultLimit property will be used.

The collection order may be controlled using the orderBy param. Format is orderBy=propertyName:asc|desc

Parameters:

pParentItemId - the id of the item that contains the category collection.

pParentItemType - the repository type of the item that contains the category collection, this will support a qualifying repository e.g. /atg/commerce/ProductCatalog:product.

pParentPropertyName - the property name containing the category collection, this supports dot

pOffset - the page start index

pLimit - the page size

pOrderBy - the repository item properties to sort results by. Direction defaults to ascending. notation for the collection to be displayed e.g. product.ancestorCategories.

Returns:

the model containing the categories and state details

Throws:

RestException - the rest exception used to highlight specific errors

RepositoryException - a repository exception indicating a server error

javax.servlet.ServletException - a servlet exception indicating a server error

getCategory

@Endpoint(id="/categories/{categoryId}#GET",
          isSingular=true,
          filterId="categories.id-Default")
public RepresentationModel getCategory(java.lang.String pCategoryId,
                                                                                                                                                           java.lang.Boolean pFilterByCatalogFlag,
                                                                                                                                                           java.lang.Boolean pFilterBySiteFlag,
                                                                                                                                                           java.lang.String pSiteId)
                                                                                                                                                    throws RestException,
                                                                                                                                                           RepositoryException

Returns a representation of a category for the given category id.

If this is a top-level resource category retrieval we will filter the category by the filterBySite, filterByCatalog & siteId query params but only if the underlying CategoryLookup droplet has its useParams set to true. If this is set to false then the query params are ignored and the corresponding CategoryLookup properties are always used.

If this is a sub-resource retrieval, i.e. embedded via another resource, we will first check the request data map to see if the parent resource had the item and passed it through. Otherwise we will check if the parent resource has indicated a direct retrieval should be done. For all the ootb resources embedding category this is set, as we always want the embedded resource to be shown. nb potential for this embedded item's self link to not work, if the top-level call is configured to be filtered by current site/catalog based on customer's CategoryLookup config - useParams, filterBySite & filterByCatalog.

OOTB the category representation includes the embedded relationship to the parentCategory; childProducts @see ProductRestResource; childCategories & relatedCategories. The REST-Jersey framework 'expand' & 'maxDepth' params can be used to control the embedded items that get expanded.

Parameters:

pCategoryId - the category to find

pFilterByCatalogFlag - if true only find the category if the category's catalog matches the user's catalog

pFilterBySiteFlag - if true only find the category if it matches the siteIds or current site context

pSiteId - site id category should belong to. If not set current site will be used

Returns:

the model containing the category and state details

Throws:

RestException - the rest exception

RepositoryException - if category repository lookup fails

getRepresentationModelBuilder

protected RepresentationModel.Builder getRepresentationModelBuilder(java.lang.Object pState)

Gets the RepresentationModel.Builder with the given object acting as the state.

Also embeds the parent category, child products, child categories and related categories.

Overrides:

getRepresentationModelBuilder in class AbstractItemLookupRestResource

Parameters:

pState - the state (assumed to be a RepositoryItem) that will be added to the representation model

Returns:

RepresentationModel.Builder containing the state