The source code for the Objective-C REST client is provided with CRS-IUA, as part of the CRS-IUA archived project files. This iOS source code is available in a separate distribution that may be accessed from the Oracle Technology Network at http://www.oracle.com/technetwork/indexes/downloads/index.html.

Note that the header files, from which HeaderDoc can be generated, are included with CRS-IUA. The headers are located <MobileCommerceiOS>/ATGRestClient/ where <MobileCommerceiOS> is the directory where you unzipped the CRS-IUA distribution.

The most important class within the Objective-C REST client is ATGRestSession. It provides clients with a way to make various types of asynchronous requests to the server using REST, and receive notification of those requests’ completion. CRS-IUA uses blocks as callbacks. Blocks provide a way to encapsulate both code and data and pass them with the request. If you are unfamiliar with blocks, please refer to the relevant iOS documentation.

For example, the signature of the ATGRestSession getComponent method is:

- (id <ATGRestOperation>) getComponent:(NSString *)pComponentPath parameters:(NSDictionary *)pParameters requestFactory:(id <ATGRestRequestFactory>)pRequestFactory options:(ATGRestRequestOptions) pOptions success:(void ( ^ ) ( id <ATGRestOperation> pOperation , id pResponseObject ))pSuccess failure:(void ( ^ ) ( id <ATGRestOperation> pOperation , NSError *pError ))pFailure;

This method allows a client to query for an Oracle ATG Web Commerce component specified by pComponentPath. You can see an example of this in the ATGProfileManager’s getProfile method, which uses the path to the profile component (/atg) as an argument to the getComponent method for ATGRestSession.

The getComponent method passes two blocks: a success block and a failure block. The operation specified in the success block is executed if the call is completed successfully:

success:(void ( ^ ) ( id <ATGRestOperation> pOperation , id pResponseObject ))pSuccess

The operation specified in the failure block is executed on errors. Usually, you use the failure block to display a message.

failure:(void ( ^ ) ( id <ATGRestOperation> pOperation , NSError *pError ))pFailure;

The requestFactory is the factory used to create the HTTP request, using the specified method, path, parameters, and ATGRestRequestOptions. If you need to extend the request factory, start with ATGDefaultRestRequestFactory. If you need to add new query parameters for use with requests, extend ATGAddParameterRestRequestFactory.

The goal of the Base ATGRestRequestFactory is to provide an extension point for developers to easily build additional, common functionality into all requests from the client to the server. The ATGRestSession should be used as the entry point for request creation and execution by iOS applications communicating with an Oracle ATG Web Commerce server via REST.

ATGRestSession provides the ATGRestRequestOptions object to encapsulate common settings that are desirable for all ATG REST requests. These class and enum definitions live in the Objective-C REST client project.

CRS-IUA also provides options (ATGMobileRestRequestOptions) within CRS-IUA’s ATGRestManager. This enum encapsulates some settings, in addition to those from ATGRestSession, that are useful for CRS-IUA specifically. An example of such a setting is the locale parameter, which the server needs for locale-specific functionality.

Within CRS-IUA, the ATGRestManager initializes a new request factory by “stacking” an ATGMultisiteRestRequestFactory on top of the ATGRestRequestFactory and passing the ATGMobileRestRequestOptions to it. The ATGRestManager then sets this new factory to be the factory used by the ATGRestSession for request creation; it is therefore used by all other managers for request creation. To learn more, see the section Managers.

It is important to note that factory and basic options enums are set on the ATGRestSession but callers can optionally override these by passing a desired options enum and/or factory on each request. For example, the ATGProfileManager’s getProfile method does not specify any options to apply, but the updatePersonalInformation call does provide options.

The ATGRestRequestOptions are Boolean flags represented as numbers so you can pass in multiple options at once. It is best to pass multiple options logically ORed together in a single expression. For example, the user’s current site, CRS Store US, CRS Store Germany, or CRS Home, and locale, which determines the language that the customer sees when viewing a site in Commerce Reference Store, are automatically added to each CRS-IUA request. However, you can turn that off on a per-request basis by including ignorePushSite and ignoreLocale options in the request.

Method to ATGRestSession for the Invocation of an Actor

Use this method in ATGRestSession to invoke an actor:

- (id <ATGRestOperation>) executePostRequestForActorPath:(NSString *)pComponentPath parameters:(NSDictionary *)pParameters requestFactory:(NSObject <ATGRestRequestFactory> *)pRequestFactory options:(ATGRestRequestOptions) pOptions success:(void ( ^ ) ( id <ATGRestOperation>operation , id responseObject ))pSuccess failure:(void ( ^ ) ( id <ATGRestOperation>operation , NSError *error ))pFailure

Note that this method takes a actor URL instead of a component path. The actor URLs, which include the actor-chain ID at the end, are in this format:

/atg/commerce/order/purchase/CommitOrderFormHandlerActor/commitOrder

The requests are made in this format:

<server>/rest/model/<actor url>

For example:

http://mobile.us.oracle.com:8180/rest/model/atg/commerce/order/purchase/CommitOrderFormHandlerActor/commitOrder