ATG Commerce Programming Guide

ATG Commerce States

In ATG Commerce, the subclasses of atg.commerce.states.ObjectStates represent the possible states for the order objects. For example, the atg.commerce.states.CommerceItemStates class represents the possible states of a CommerceItem, the atg.commerce.states.PaymentGroupStates class represents the possible states of a PaymentGroup, and so on. The state names are defined in static String variables in each state class, and ATG Commerce code uses the state name to set the state of a given object. For example:

// set the state of shippingGroup to the integer value of the
// PENDING_SHIPMENT state. sgStates.PENDING_SHIPMENT is the
// name of the state
ShippingGroupStates sgStates = getShippingGroupStates();
shippingGroup.setState(sgStates.getStateValue(sgStates.PENDING_SHIPMENT));

ATG Commerce provides the following configured instances of the state classes, which are located in Nucleus at /atg/commerce/states/:

OrderStates: indicates the states of an Order.

CommerceItemStates: indicates the states of a CommerceItem.

PaymentGroupStates: indicates the states of a PaymentGroup.

ShippingGroupStates: indicates the states of ShippingGroup.

ShipItemRelationshipStates: indicates the states of a ShippingGroupCommerceItemRelationship.

The properties files of these state objects configure the following properties, which provide mappings of the order object’s state names to corresponding String values (for easy reading) and integer values (for easy comparisons):

stateValueMap: maps each state name to an Integer value.

stateStringMap: maps each state’s Integer value to a display name. This is the String value that users see and that is stored in the repository.

stateDescriptionMap: maps each state’s Integer value to a String description of the state.

Note that a state’s name and display name are two different values.

Each state class (OrderStates, CommereItemStates, and so on) contains several methods for retrieving a requested state’s Integer value, display name, or description from the state mappings. The following table describes these methods:

Method name

Description

getStateValue

Given a state name, this method returns its Integer value.

getStateFromString

Given a state’s display name, this method returns its Integer value.

getStateString

Given a state’s Integer value, this method returns its display name.

getStateDescription

Given a state’s Integer value or display name, this method returns its description.

getStateAsUserResource

Given a state’s Integer value or display name (as configured in the properties file of the relevant states component, for example, OrderStates.properties or CommerceItemStates.properties), this method returns the display name that is defined in the resource file that is appropriate for the current locale.

Note: Used for internationalization, as described below.

getStateDescriptionAsUserResource

Given a state’s Integer value or display name (as configured in the properties file of the relevant states component, for example, OrderStates.properties or CommerceItemStates.properties), this method returns the state’s description that is defined in the resource file that is appropriate for the current locale.

Note: Used for internationalization, as described below.

The methods in the preceding table are called by several methods in the implementation classes of the order objects. Consequently, to retrieve the Integer value for the state of an order object, you can simply call the getState method of that order object. For example, call OrderImpl.getState to retrieve the corresponding Integer value for the state of the Order from OrderStates.properties. Similarly, call CommerceItemImpl.getState to retrieve the corresponding Integer value for the state of the CommerceItem from CommerceItemStates.properties.

Additionally, if your commerce site isn’t internationalized, use the following order object methods to retrieve the display name or description, respectively, for the state of the order object. Like the getState method, these methods retrieve a value specified in the properties file of the relevant states component:

getStateAsStringFor example, call OrderImpl.getStateAsString to retrieve the display name for the state of the Order object from OrderStates.properties. Similarly, call CommerceItemImpl.getStateAsString to retrieve the display name for the state of the CommerceItem from CommerceItemStates.properties.

getStateDetailFor example, call OrderImpl.getStateDetail to retrieve the description for the state of the Order object from OrderStates.properties. Similarly, call CommerceItemImpl.getStateDetail to retrieve the description for the state of the CommerceItem from CommerceItemStates.properties.

If your commerce site is internationalized, and you, therefore, need to provide one or more translations of the display names and descriptions for the states of the ATG Commerce order objects, then you should specify those values in ResourceBundle.properties files that are placed in the CLASSPATH. By default, ATG Commerce provides a base ResourceBundle.properties file named StateResources.properties, which is used when a locale-specific resource file isn’t found during a request. The StateResources.properties file maps each state’s configured display name to a translated display name and description using the following key-value format:

ORDERDESC.INCOMPLETE=The order is incompleteORDERDESC.SUBMITTED=The order has been submitted to FulfillmentSHIPPINGDESC.INITIAL=The shipping group has been initializedSHIPPINGDESC.FAILED=The shipping group has failedITEMDESC.INITIAL=The item has been initializedITEMDESC.PENDING_REMOVE=The item is pending remove request

Note that the keys are the display names of the states as configured in the properties files of the states components (OrderStates.properties, ShippingStates.properties, and so on). Also note that, because different order objects may use the same display name for a given state, each key is prepended with a prefix to avoid conflict.

To add an additional resource file, copy StateResource.properties and rename the file according to Java naming guidelines for ResourceBundle inheritance, using any appropriate language, country, and variant suffixes. Then translate the file according to the translation guidelines provided in the Internationalizing a Dynamo Web Site chapter in the ATG Programming Guide. (You can refer to that chapter for more information on working with ResourceBundles.) Finally, place the resource file in the CLASSPATH. By default, StateResources.properties is located in the CLASSPATH at atg.commerce.states.StateResources.properties, and each states component refers to this file in its resourceFileName property (OrderStates.resourceFileName, CommerceItemStates.resourceFileName, and so on). However, note that in ATG Business Commerce, OrderStates.resourceFileName only is set to atg.b2bcommerce.states.StateResources.properties, which includes resources for some additional Order object states.

If your commerce site is internationalized and, therefore, makes use of StateResources.properties resource files, use the following order object methods to retrieve a locale-specific display name or description, respectively, for the state of the order object:

getStateAsUserResourceFor example, call OrderImpl.getStateAsUserResource to retrieve a locale-specific display name for the state of the Order object from the appropriate StateResources_XX.properties file.

getStateDescriptionAsUserResourceFor example, call OrderImpl.getStateDescriptionAsUserResource to retrieve a locale-specific description for the state of the Order object from the appropriate StateResources_XX.properties file.

Like the other order object methods, these methods call through to the methods in the states classes (OrderStates, CommerceItemStates, and so on), namely the getStateAsUserResource and getStateDescriptionAsUserResource methods. Given the current locale and the basename specified in the resourceFileName property of the states component (OrderStates.resourceFileName, CommerceItemStates.resourceFileName, and so on), these latter methods use ResourceBundle inheritance rules to retrieve the most appropriate resource file for the current locale. For example, if the locale is fr_FR, the code first looks for a StateResources_fr_FR.properties file. If the file doesn’t exist, it then looks for a StateResources_fr.properties file. If that file doesn’t exist, it retrieves the default resource file, StateResources.properties. Once the appropriate resource file is obtained, the appropriate prefix is appended to the key, and the requested value is retrieved.

As previously mentioned , in ATG Commerce the subclasses of atg.commerce.states.ObjectStates represent the possible states for the order objects. You can refer to the subsections that follow for descriptions of these states: