In Core 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 Core 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));

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

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):

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

For example, the OrderStates.properties file contains values such as:

stateValueMap=\
              incomplete=0,\
              submitted=1,\
              processing=2,\

…
stateStringMap=\
               0=INCOMPLETE,\
               1=SUBMITTED,\
               2=PROCESSING,\

…
stateDescriptionMap=\
                    0=Incomplete,\
                    1=Submitted to fulfillment,\
                    2=Processing,\
…

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:

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 is not 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:

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 Core Commerce order objects, then you should specify those values in ResourceBundle.properties files that are placed in the CLASSPATH. By default, Core Commerce provides a base ResourceBundle.properties file named StateResources.properties, which is used when a locale-specific resource file is not 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 formats:

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 Platform 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).

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:

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 base name 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 does not exist, it then looks for a StateResources_fr.properties file. If that file does not 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 Core 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: