ATGWSFrame Guide

Version 10.1.
Web Services and Integration Framework Guide
Oracle ATG One Main Street Cambridge, MA 02142 USA
ATG Web Services and Integration Framework Guide

Product version: 10.1.1 Release date: 07-20-12 Document identifier: WebServicesGuide1209062105 Copyright 1997, 2012 Oracle and/or its affiliates. All rights reserved. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government. This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services. The software is based in part on the work of the Independent JPEG Group.
Table of Contents
I. Creating and Using Web Services in the ATG Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1. ATG Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Creating Custom Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Overview of ATG Web Services Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 JAX-RPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Automatic Generation of Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Session and Security Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Web Service Creation Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Using the Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Naming Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Anatomy of a Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Service Endpoint Interface and Implementation Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 WSDL Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 web.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 JAX-RPC Deployment Descriptor and Mapping Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Runtime Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 JSR 109 Compliant EAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Web Service Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Security Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Creating and Editing Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Deploying Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Managing Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Registering Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3. Creating JMS Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Using the JMS Message Web Service Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Structure of a JMS Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Patch Bay Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 4. Creating Repository Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Using the Repository Web Service Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Repository Web Service Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Modifying Repository Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 RepositoryService Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 5. Repository to XML Data Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Mapping Files and XML Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Mapping Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Managing Mapping Files for Repository Item Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 XML Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Managing Schemas and Mapping Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 PropertyElementNameSeparator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Item References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Repository Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Getting Repository Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Adding Repository Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Updating Repository Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Removing Repository Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 6. Accessing ATG Web Services from Java Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 About ATG Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Sharing Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
iii
RepositoryItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before You Begin Using a Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing a CookieContainer Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calling ATG Web Services from a Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Call Using a Client Stub (Static) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Call Using the Dynamic Invocation Interface (Dynamic) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Serializer and Deserializer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Mapping File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating an XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7. Accessing ATG Web Services from .NET Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About Web Services in the ATG Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Session Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Web Services that Access RepositoryItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before You Begin Using a .NET Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing ATGWS.dll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calling ATG Web Services from a .NET Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing an ATG Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing a Custom ATG Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Web Service Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Atg.DotNet.WebService API to Serialize and Deserialize RepositoryItems . . . . . . . . . . . . . . . . . RepositoryItem Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Property Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RepositoryItemRef Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Complex Type Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NoSuchPropertyException Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RepositoryItemSerializer Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RepositoryItemSerializationException Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . II. Integration Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8. Using the Integration Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integration Approaches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remote Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remote then Local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Local then Remote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Local Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up an Integration Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining an Integration Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integration Repository APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IntegrationRepository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IntegrationRepositoryItemDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IntegrationRepositoryItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ChangedPropertyBean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . atg.repository.databinding.MappingRepositoryItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IntegrationRepositoryView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . executeQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . updateItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . addItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
44 45 45 47 48 50 51 51 52 55 55 55 56 56 56 56 57 57 58 58 58 59 60 62 63 63 64 64 65 65 67 69 69 70 70 70 71 71 72 72 73 74 76 77 77 77 78 79 79 80 80 81 81
iv
Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Persistent Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Cleaning up the Persistent Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Configuration Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Configuring the Remote-Only Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Configuring the Remote-then-Local Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Configuring the Local-then-Remote Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Integration Repository Definition File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 integration-repository-template tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 header tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 item-descriptor tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 item-descriptor Child Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 integration-repository Document Type Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 9. Remote Procedure Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 RPC API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Command Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 CommandHandler Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 CommandResult Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Implementing the RPC API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Executing Commands in Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 III. ATG Platform REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 10. Using REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Starting the REST module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 HTTP Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 REST Web Services URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Client Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 HTTP Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Handling POST Requests as Other Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Handling Session Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Logging In as an External User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Logging In as an Internal User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Logging Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Control Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Control Parameter Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Functional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Positional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 URL Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Message Body Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Setting the Content-Type Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 XML Parameter Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 JSON Parameter Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 URL Query String Parameter Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Input Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Primitive Values in Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Multiple Values in Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Object Values in Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Nested Multiple Value Objects in Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Date Format in Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Setting Properties to Null . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 HTTP Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Returned Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Choosing Output Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JSON Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Identifying a Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Multiple Values in Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Return Depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Date Format in Returned Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Problems Performing Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Problems Processing a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11. Working with Component Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Component Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Component Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12. Invoking Component Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13. Invoking Form Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting Form Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Returning Form Handler Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Returning Form Handler Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form Value Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14. Invoking Java Server Pages (JSPs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REST Web Services JSP Configuration Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . URL Templates for REST Web Services JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the REST ServiceProcessor Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example REST Web Services JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15. Working with Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing Repository Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieving a Repository Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieving a Specific Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing RQL Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Repository Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transient Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Repository Item Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting a Repository Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16. Property Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Default Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Filter Depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filtering Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filtering for One Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Property Aliasing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Suppressing Property Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Suppressing Property Expansion for Java Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Suppressing Property Expansion for Specific Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filtering Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17. Configuring the REST Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . /atg/rest/Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . defaultOutputCustomizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . maxDepthAllowed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . /atg/rest/processor/BeanProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . returnFormHandlerExceptionsByDefault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . returnFormHandlerPropertiesByDefault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . /atg/rest/output/JSONOutputCustomizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . enableFormatDateOutput for JSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . enablePerRequestFilters for JSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
126 127 127 128 129 134 135 135 136 137 139 139 140 143 145 146 146 147 148 149 150 151 152 152 155 155 156 157 158 160 161 162 163 165 165 167 168 169 170 171 171 172 172 173 173 173 173 173 174 174 174 174 174
vi
enablePerRequestComponentFilters for JSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . enablePerRequestRepositoryFilters for JSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . enablePerRequestClassFilters for JSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . showRestPaths for JSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . /atg/rest/output/XMLOutputCustomizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . enableFormatDateOutput for XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . enablePerRequestFilters for XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . enablePerRequestComponentFilters for XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . enablePerRequestRepositoryFilters for XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . enablePerRequestClassFilters for XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . showRestPaths for XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . /atg/rest/processor/RepositoryProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . acceptJSONInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . appendMultiValuesByDefault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . /atg/rest/processor/RestSecurityProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . allowAccessForUnsecuredRepository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18. Security for REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Security Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging In and Session IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Nucleus Component Granularity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Quick Setup for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Component Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Property and Method Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Repository Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Securing Groups of Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19. ATG Client Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a RestSession Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting a REST Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging in and Logging Out with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting a Session Without Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Data from the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Raw REST Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Handling Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Components with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calling Methods with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Repository Items with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Java Client in Android Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ActionScript Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . atg.rest.client.RestComponentHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . atg.rest.client.RestRepositoryHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calling Methods with ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Formatting Input with ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
175 175 175 175 176 176 176 176 176 177 177 177 177 178 178 178 179 179 179 179 180 180 181 181 182 182 183 183 183 185 186 187 189 189 190 191 192 193 194 197 197 198 199 199 201 203
vii
viii
Part I. Creating and Using Web Services in the ATG Platform

A common requirement for enterprise applications is the ability to share data and business logic with other applications. For example, suppose you have an employee portal built with the Oracle ATG Web Commerce platform, and also a payroll system based on some other software package. When a new employee starts, or an existing employee changes his or her marital status, you need to create or modify the employees profile in both systems. Ideally, youd like the employee to be able to make the changes in one application and have those changes automatically propagate to the other application. One way to address this issue is through Web Services, a widely supported standard for packaging remote procedure calls in an XML-based structure. In the example above, you could create a Web Service that automatically updates an employees profile in the employee portal when the information in the payroll system is modified. The Dynamo Application Framework includes tools that allow you to create custom Web Services that call methods on Nucleus components. These custom Web Services can expose methods on existing Oracle ATG Web Commerce Nucleus components, or on Nucleus components you write yourself. You can call these Web Services from an external application client, such as the payroll system mentioned above. The Oracle ATG Web Commerce platform packages Web Services as: J2EE applications, in accordance with the JAX-RPC (JSR 101) and Implementing Enterprise Web Services (JSR 109) specifications. Note that this manual assumes that youre familiar with these specifications, and with Web Services in general. For more information about these specifications, see the Java Community Process web site at:
http://www.jcp.org
The chapters in this section discuss how to create Web Services in the Oracle ATG Web Commerce platform, and how to write Java and .NET clients that call these services: Creating Custom Web Services (page 5) Creating JMS Web Services (page 19) Creating Repository Web Services (page 23) Repository to XML Data Binding (page 27) Accessing ATG Web Services from Java Clients (page 43) Accessing ATG Web Services from .NET Clients (page 55)
ATG Web Services
In addition to any Web Services you create, the Oracle ATG Web Commerce platform includes a number of prepackaged Web Services that you can call from Java and .NET clients. These services are packaged in three separate application modules. You can include any of these services in an assembled EAR file by including the module that contains the desired services. For example, to include the prepackaged Commerce Web Services, specify the DCS.WebServices module when you assemble your application. The following table summarizes these Web Services:
Application Module
DAS.WebServices
Web Application Generic Repository Services
Web Services
- getRepositoryItem - performRQLQuery - performRQLCountQuery
For more information about these Web Services, see the ATG Repository Guide.
DPS.WebServices
User Session
For more information about these Web Services, see the ATG Personalization Programming Guide
loginUser logoutUser getProfileId setLocale setContactInfo setPassword getProfile createUser updateUser getPasswordHashKey getPasswordHashAlgorithm canClientEncryptPasswords executeRepositoryTargeter
Messaging
- sendPageVisit - sendClickThrough
1 ATG Web Services
Application Module
DCS.WebServices
Web Application Order
Web Services
createOrderFromXML submitOrderWithReprice cancelOrder getOrderStatus getOrderAsXML getOrdersAsXML getOrderStatus getCurrentOrderId addItemToOrder addItemToShippingGroup createOrder createOrderForUser removeItemFromOrder setItemQuantity addCreditCardToOrder addShippingAddressOrder removePaymentGroupFromOrder removeCreditCardFromOrder removeShippingGroupFromOrder moveItemBetweenShippingGroups removeItemQuantityFromShippingGroup setOrderAmountToPaymenGroup getDefaultPaymentGroupId getDefaultShippingGroupId
For more information about these Web Services, see ATG Commerce Programming Guide.
Pricing
- calculateOrderPrice - calculateOrderPriceSummary - calculateItemPriceSummary grantPromotion revokePromotion claimCoupon getPromotionsAsXML getInventory getInventoryStatus setStockLevel setStockLevels getProductXMLById getProductXMLByDescription getProductXMLByRQL getProductSkusXML catalogItemViewed setDefaultShippingAddress setDefaultBillingAddress setDefaultCreditCard getDefaultShippingAddress getDefaultBillingAddress getDefaultCreditCard
Promotions
Inventory
Catalog
Profile
1 ATG Web Services
Creating Custom Web Services
The Oracle ATG Web Commerce platform provides infrastructure and tools that enable you to expose a wide range of Oracle ATG Web Commerce functionality as Web Services. There are three kinds of Web Services you can create that expose Oracle ATG Web Commerce functionality: Web Services that invoke methods on Nucleus components. Web Services that send JMS messages through Patch Bay. Web Services that perform operations on repository items. This chapter describes the infrastructure for creating these services. It focuses on Web Services that invoke Nucleus methods, but most of what is described here applies to all three types of services. For information specific to Web Services that send JMS messages, see the Creating JMS Web Services (page 19) chapter. For information specific to Web Services that perform repository operations, see the Creating Repository Web Services (page 23) chapter. This chapter includes the following sections: Overview of ATG Web Services Support (page 5) Web Service Creation Wizard (page 7) Anatomy of a Web Service (page 9) Web Service Security (page 13) Deploying Web Services (page 15) Managing Web Services (page 16)
Overview of ATG Web Services Support

This section describes key aspects of Oracle ATG Web Commerce Web Services support: JAX-RPC Automatic generation of Web Services Session and security support Limitations
2 Creating Custom Web Services
JAX-RPC
The Web Services support in the Oracle ATG Web Commerce platform is based on JAX-RPC (Java API for XMLbased RPC). The JAX-RPC specification defines a standard way for incoming XML-based SOAP messages to be converted to Java-based RPC calls. The Oracle ATG Web Commerce platform uses Oracles reference implementation of JAX-RPC. Parts of this reference implementation are used to generate Web Services, and other parts of it handle the processing of SOAP messages when a Web Service is called.
Automatic Generation of Web Services

Creating a Web Service by hand can be a laborious process, due to the large number of Java and XML files you must create and package. The Oracle ATG Web Commerce platform automates this process through the Web Service Creation Wizard in the Dynamo Administration UI. You select the type of service you want to generate, and the wizard takes you through a series of screens where you specify the necessary information. You then click a button, and the wizard automatically generates the necessary classes, WSDL documents, and deployment descriptors, and packages them in EAR and WAR files.
Session and Security Support

When you create a Web Service, you specify whether it should be executed within the context of an HTTP session. Associating Web Services with a session enables an application to maintain state across Web Service calls and to use login information for security purposes. To enable multiple Web Services to execute within the same session, a client application must pass a session cookie between calls. Some Web Services frameworks, such as Microsofts .NET, provide support for passing session cookies. Java clients typically require applications to manage session cookies themselves. For more information about using sessions with Java clients, see the Accessing ATG Web Services from Java Clients (page 43) chapter. For more information about using sessions with .NET clients, see the Accessing ATG Web Services from .NET Clients (page 55) chapter.
Limitations
You can create Web Services from most Nucleus methods, both from components Oracle ATG Web Commerce provides and components that you write. There are, however, some methods that cannot be exposed as valid Web Services. The Web Service Creation Wizard will not create Web Services from these methods. In particular, it enforces the following restrictions by preventing you from selecting these methods: You cannot create a Web Service from any method that has a parameter or return type that is an abstract data type (such as a Map, Collection, Interface, abstract class, or an object with abstract data type properties). You cannot create a Web Service from any method that has a parameter or return type that is a wrapper class for a primitive data type. The prohibited classes are Byte, Boolean, Character, Integer, Short, Long, Float, and Double. Note, however, that methods that use actual primitives are valid. If there is a method that you want to expose that has one of these wrapper classes as a parameter or return type, you can either rewrite the method to use a primitive instead (if the methods class is your own custom code), or else subclass the methods class (if it is a class provided by Oracle ATG Web Commerce) and overload the method with a version that uses primitives. In addition, you cannot create a Web Service from a method that has the same name and signature as any of the methods of atg.webservice.ManagedComponentProperties or java.lang.Object. Attempting to
do so results in a naming conflict, because the service implementation class of each Web Service subclasses atg.webservice.ManagedComponentProperties, which subclasses java.lang.Object. Note that the wizard does not prevent you from selecting these methods, but when you try to generate a Web Service, an exception is thrown and the service generation fails.
Web Service Creation Wizard

The process of creating Web Services is automated by the Web Service Creation Wizard in the Dynamo Administration UI. This wizard guides you through the steps of selecting a Nucleus component and method, specifying input parameters and other settings; it then automatically creates the Web Service by performing the following steps: Create the service endpoint interface that specifies the method to be exposed. Create the service endpoint class that implements the service endpoint interface and is responsible for handing incoming SOAP requests. Create the WSDL document that describes the resources required by the service endpoint class, as well as its inputs and outputs. Create the web.xml file for the Web application that the service is a part of. Create the JAX-RPC deployment descriptor (webservices.xml) and mapping file. Build the runtime classes. Package these elements in a JSR 109 compliant EAR file. These steps are described in more detail in the Anatomy of a Web Service (page 9) section. The wizard uses the component /atg/webservice/WebServiceGenerator to perform the actual work of generating the service. This component, which is of class atg.webservice.WebServiceGeneratorImpl, performs all of the operations listed above, either through its own methods or through other components it refers to.
Using the Wizard

The top-level page of the Dynamo Administration UI includes a Web Service Administration link. This link takes you to the Web Service Administration page, which has three links for working with Web Services: Web Service Registry Takes you to a page for viewing and managing currently loaded Web Services. The Web Services registry is discussed in the section Managing Web Services (page 16). Web Service Security Manager Enables you to create and edit Web Service security configurations. These security configurations can be used to define which users can access specific Web Services. When you create a Web Service, you have the option of associating a security configuration with the service. Security configurations are discussed in the section Web Service Security (page 13). Web Service Creation Wizard Takes you to a page with links for creating each of the three kinds of Web Services (Component Method Web Service, JMS Message Web Service, Repository Web Service).
To create a Web Service that invokes a method on a Nucleus component, starting from the Web Service Administration page: 1. Click the Web Service Creation Wizard link. This takes you to a page titled Select Type, where you can select the type of Web Service to create. 2. Click the Component Method Web Service link. This takes you to the Select Nucleus Component page. 3. On the Select Nucleus Component page, specify the pathname of the Nucleus component you want to create the Web Service from. You can either enter the pathname directly in the field at the top of the page and then click the Next button, or you can use the component browser below it to navigate to the component and select it. 4. On the Select A Method page, select the method you want to expose as a Web Service. 5. If the method requires any input parameters, the Set Parameter Names page provides you with fields for specifying the names of these parameters. The names you specify are used for the parameters of the Web Service call, and can be anything you like. When the Web Service is called, the service passes the values of these parameters to the parameters of the exposed Nucleus method. There is thus a one-to-one correspondence between the parameters of the Web Service call and the parameters of the underlying Nucleus methods. 6. The next two pages are titled EAR Name & Servlet Settings and Enterprise and Web Application Settings. When the wizard creates a Web Service, it packages it in a WAR file, which is in turn packaged in an EAR file. It is possible to have any number of services in a single Web application (WAR file), and any number of Web applications in a single Enterprise application (EAR file). This flexibility gives you a good deal of control over how you deploy your Web Services. For each new Web Service, the wizard can do any of the following: Create a new EAR file for the service, and put it in a WAR file within the EAR file. Use an existing EAR file, and put the service in a new WAR file within it. Put the service in an existing WAR file within an existing EAR file. To add a Web Service to an existing EAR file, you specify that file as the EAR file name on the EAR Name & Servlet Settings page. The Web Application Settings page then gives you the choice of creating a new Web application for the service, or adding the service to an existing Web application. The wizard also gives you the option of specifying the host name and port number for a Web Service, or of leaving these fields blank. If you leave the fields blank, the values are dynamically assigned at runtime from the URL used for the WSDL file request. 7. The Session & Security Options page allows you to specify whether the Web Service should be executed within the context of an HTTP session. The wizard gives you these options: Neither provide a session nor security constraints. Provide a session, but no security constraints. Provide both a session and security constraints. If you want to call the Web Service from a client that uses sessions or session sharing, you must choose one of the last two options. If you choose the last option, the wizard then prompts you to select a security configuration. See Web Service Security (page 13) for information about security configurations for Web Services. 8. On the Create EAR File page, click the Create EAR File button to create the Web Service.
If there is already an EAR file with the specified name, the wizard first appends .old to the name of the existing file so that new file does not overwrite it. Once you have created an EAR file, you must deploy it in order to run the Web Services in it. See the Deploying Web Services (page 15) section for more information.
Naming Restrictions
Most of the class names and filenames for Web Services are generated automatically by the wizard. As a result, certain circumstances can result in naming conflicts. For example, if you create a Web Service from a Nucleus method, you cannot then create a second Web Service from another method with the same name (such as an overloaded method) and put it in the same WAR file, even if the two methods have different signatures or capitalization. If you attempt to do this, the second Web Service will simply overwrite the first. To prevent the second service from overwriting the first, put the second service in a different WAR file. In addition, be sure to give the second WAR file a different context root from the first WAR file. (The default value for the context root in the wizard is based on the method name, so youll need to change the value when you run the wizard.) It will then be possible to differentiate calls to the two services based on their context roots.
Anatomy of a Web Service

As mentioned above, the Web Service Creation Wizard automatically performs a number of tasks, greatly simplifying the creation of Web Services from Nucleus components. The wizard enables you to simply create Web Services and begin using them, without needing to understand all of their underpinnings. However, in some cases you may need to troubleshoot or make changes to your Web Services, so it is helpful to have some familiarity with their form and packaging. This section discusses the various pieces that make up a Web Service, including: service endpoint interface and implementation class WSDL document web.xml file JAX-RPC deployment descriptor (webservices.xml) and mapping file runtime classes JSR 109 compliant EAR file Note that the business logic of the Web Service is actually contained in the method of the Nucleus component that is being exposed. The Web Service handles only the RPC infrastructure, and passes the actual processing to the Nucleus component.
Service Endpoint Interface and Implementation Class

The service endpoint interface (SEI) is a Java interface class that defines the methods to be exposed as a Web Service. This interface must extend the java.rmi.Remote interface and each method must throw java.rmi.RemoteException. The SEI for any Web Service generated by the Oracle ATG Web Commerce platform has a single method, corresponding to the Nucleus method being exposed.
The service implementation class (also referred to as the service bean) implements the service endpoint interface and handles the actual servicing of incoming SOAP requests. In addition, service implementation classes generated by the Oracle ATG Web Commerce platform implement the interface javax.xml.rpc.server.ServiceLifecyle, and extend the atg.webservice.ManagedComponentProperties class, which registers services with the Oracle ATG Web Commerce platform Web Service Registry. The Web Service Registry is discussed in the Managing Web Services (page 16) section. The service endpoint interface and implementation class are generated by the /atg/webservice/ WebServiceGenerator component. The names for these classes are based on the name of the Nucleus method being exposed. For instance, if the Nucleus method is getOrderStatus, the service endpoint interface is named GetOrderStatusSEI, and the implementation class is named GetOrderStatusSEIImpl.
WSDL Document
Web Services Description Language (WSDL) is an XML language for describing Web Services in a platformindependent way. A WSDL document describes a Web Services methods by specifying the locations of the resources they use and defining the methods inputs and outputs. (A WSDL document for a Web Service generated by the Oracle ATG Web Commerce platform always describes one method, because each Web Service can expose only one Nucleus method.) There must be a separate WSDL document for each Web Service. The WSDL document is generated by the / atg/webservice/WSDLGenerator component, which is of class atg.webservice.WSDLGeneratorImpl. This document is used for two key purposes: It is used by the JAX-RPC API to generate runtime classes. At runtime, it is used by Web Service clients to look up the semantics of the SOAP messages to send to invoke the service. When the Web Services input and output values are primitive types, they are defined in the primary WSDL document. For example:
<message name="getOrderStatusInput"> <part name="in0" type="xsd:string"> </message>
Each non-primitive input or output requires its own WSDL document that is imported by the primary WSDL document. Import statements similar to the following are included in the primary WSDL document when the Web Service is created using the Dynamo Administration UI:
<import location="atg.commerce.order.status.wsdl" namespace="http://www.atg.com/atg.commerce.order.status"/>
The location specified is relative to the primary WSDL document. Some Web Service clients are able to interpret relative locations, but others require fully qualified URLs. To work with these clients, when the Oracle ATG Web Commerce platform receives a request for a WSDL document, it uses the servlet class atg.webservice.WSDLFinderServlet and the filter class atg.webservice.WSDLImportFilter to translate the location value into a fully qualified URL: 1. At runtime, JAXRPCServlet updates the SOAP address in the WSDL document to include the domain host name and port number.
10
2. When WSDLFinderServlet detects a WSDL request, WSDLImportFilter appends the domain name and port number (from the SOAP address provided by JAXRPCServlet) and the context path (by calling request.getContextPath() on the Dynamo request) to the location value in the import statement. The resulting import statement looks similar to this:
<import location= "http://myhost:7881/catalog/atg.commerce.order.status.wsdl" namespace="http://www.atg.com/atg.commerce.order.status"/>
The WSDLFinderServlet and WSDLImportFilter classes are declared in the web.xml file for the Web application that the Web Service is a part of, as discussed in the next section. For more information about request handling, see the ATG Platform Programming Guide.
web.xml File
The web.xml file is the standard deployment descriptor for the Web application that the Web Service is a part of. It declares the filters and servlets used by the service. On the Oracle ATG Web Commerce platform, the servlet that listens for the SOAP request is com.sun.xml.rpc.server.http.JAXRPCServlet. This servlet is part of the JAX-RPC reference implementation, and is responsible for receiving the incoming SOAP request and determining how to dispatch the call. For example, if you create a Web Service called getOrderStatus, the entry for it in the web.xml file looks something like this:
<servlet> <servlet-name>getOrderStatus</servlet-name> <display-name>getOrderStatus</display-name> <servlet-class>com.sun.xml.rpc.server.http.JAXRPCServlet</servlet-class> <init-param> <param-name>configuration.file</param-name> <param-value>WEB-INF/wsconfig/getOrderStatus_Config.properties</param-value> </init-param> </servlet> ... <servlet-mapping> <servlet-name>getOrderStatus</servlet-name> <url-pattern>/getOrderStatus/*</url-pattern> </servlet-mapping>
When a call to the getOrderStatus Web Service is sent to the Oracle ATG Web Commerce platform, the JAXRPCServlet receives the request and dispatches it based on the information in the file that the configuration.file parameter points to. This configuration file is included in the WAR file, and looks similar to this:
port0.wsdl.serviceName=GetOrderStatusSEIService port0.tie=webservices.GetOrderStatusSEI_Tie wsdl.transform=true port0.name=getOrderStatus portcount=1 wsdl.location=WEB-INF/getOrderStatus.wsdl port0.servant=webservices.GetOrderStatusSEIImpl port0.wsdl.targetNamespace=http\://www.atg.com/webservices port0.wsdl.portName=GetOrderStatusSEIPort
11
Note that the port0.servant property is set to the name of the service implementation class. This property designates the class that JAXRPCServlet dispatches the SOAP request to.
Handling Imported WSDL Documents

As discussed in the WSDL Document section, there are two resources that assist in handling WSDL requests. These resources are declared in the web.xml file: WSDLImportFilter, which is a filter of class atg.webservice.WSDLImportFilter, is mapped to a parent directory that has subdirectories holding WSDL documents. WSDLFinder, which is a servlet of class atg.webservice.WSDLFinderServlet, should be defined and mapped to each path that will lead to a WSDL document. For example:
<filter> <filter-name>WSDLImportFilter</filter-name> <filter-class>atg.webservice.WSDLImportFilter</filter-class> </filter> ... <filter-mapping> <filter-name>WSDLImportFilter</filter-name> <url-pattern>/getOrderStatus/*</url-pattern> </filter-mapping> ... <servlet> <servlet-name>WSDLFinder</servlet-name> <display-name>WSDLFinder</display-name> <description>Used to lookup imported wsdl files.</description> <servlet-class>atg.webservice.WSDLFinderServlet</servlet-class> </servlet> ... <servlet-mapping> <servlet-name>WSDLFinder</servlet-name> <url-pattern>atg.commerce.order.status.wsdl</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>WSDLFinder</servlet-name> <url-pattern>atg.security.wsdl</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>WSDLFinder</servlet-name> <url-pattern>atg.commerce.wsdl</url-pattern> </servlet-mapping>
Web Service Registrar

To register Web Services with the Web Services Registry, the web.xml file declares the WebServiceRegistrar servlet, and sets it to load on startup:
<servlet> <servlet-name>WebServiceRegistrar</servlet-name> <display-name>WebServiceRegistrar</display-name> <description>ATG WebServiceRegistrar for registering servlet web-services.</description> <servlet-class>atg.webservice.WebServiceRegistrar</servlet-class>
12
<load-on-startup>1</load-on-startup> </servlet>
For more information about the Web Services Registry, see Managing Web Services (page 16).
Other Elements of web.xml

The web.xml file may declare certain additional elements: the servlet atg.nucleus.servlet.NucleusServlet, which runs Nucleus as a servlet within a Web application the filter atg.filter.dspjsp.PageFilter, which invokes the DAF request-handling pipeline the context parameter atg.session.parentContextName; its value is set to /dyn, which enables the Web Services to share information with the atg_bootstrap.war application
JAX-RPC Deployment Descriptor and Mapping Files

The JAX-RPC deployment descriptor, webservices.xml, provides metadata (such as names and descriptions of the SEIs, service beans, and WSDL documents) about all of the Web Services in a given Web application. The mapping file defines the association between a WSDL file and an SEI and implementation class, by mapping namespaces to Java packages. This mapping is used when serializing and deserializing XML files. There is a separate JAX-RPC mapping file for each Web Service, and the name of each file reflects the method the service is based on. For example, if the method is getOrderStatus, the mapping file for the Web Services is named getOrderStatusMapping.xml.
Runtime Classes
The runtime classes are generated using the Oracle JAX-RPC reference implementation. These classes include: the tie class that JAXRPCServlet invokes the method on, and which in turn invokes the method on the service implementation class classes for handling serializing and deserializing SOAP requests and responses
JSR 109 Compliant EAR File

The JSR 109 Java specification includes information about how a Web Service should be packaged within an EAR file. The wizard combines all the generated files (class files, web.xml, WSDL document, webservices.xml, and JAX-RPC mapping file) into a WAR file, which is then added to a JSR 109 compliant EAR file.
Web Service Security

When you create a Web Service, you have the option of applying security constraints so that only approved clients (those with administrator privileges, for example) can execute it. You specify the security constraints using a security configuration, which is a repository item that stores information that controls access to
13
the Web Service. You can create any number of different security configurations using the Web Services Administration UI, and you can apply a security configuration to any number of Web Services. A security configuration has a corresponding security policy component, plus an optional ACL. A security configuration is identified by its functional name, which is a property of the repository item that maps the security configuration to a security component and ACL. This section describes the main components involved in securing Web Service methods, as well as how to create security configurations through the Web Services Administration UI. For a broader discussion of the Oracle ATG Web Commerce security API, see the Managing Access Control chapter in the ATG Platform Programming Guide.
Security Components
There are two primary components involved in securing a Web Service method: /atg/webservice/security/NucleusSecurityManager (an instance of atg.webservice.NucleusSecurityManager) uses the security configuration associated with the Web Service to apply the corresponding security policy and ACL, to determine whether to grant or deny access. /atg/webservice/security/NucleusSecurityRepository (an instance of atg.adapter.gsa.GSARepository) stores the Web Service security configurations used by the NucleusSecurityManager.
NucleusSecurityManager
At startup time, the NucleusSecurityManager retrieves the repository items from the NucleusSecurityRepository (described below) and creates an internal mapping between each functional name and the SecurityPolicy component and ACL associated with it. When a client calls a Web Service, the service invokes the hasAccess() method on the /atg/webservice/ security/NucleusSecurityManager component, passing it the functional name of the services security configuration, the name of the Nucleus component and method exposed by the service, and a Map containing the methods parameters. The NucleusSecurityManager uses the functional name to find the associated SecurityPolicy component and ACL, applies them to the call, and returns the result (true or false) to the client. If true is returned, the Nucleus method exposed by the Web Service is invoked; if false is returned, access to the method is denied, and an exception of class atg.security.SecurityException is thrown. If the NucleusSecurityManager is unable to apply the security configuration to a Web Service call (for example, if the SecurityPolicy is not valid), it determines whether to grant access based on the value of its defaultGrantAccess property. The default value of this property is false (deny access). Setting defaultGrantAccess to true facilitates the development process, because it allows any Web Service that does not have an associated security configuration to be called by any client. For deployment purposes, though, this behavior is undesirable, because of the security risks involved. Therefore, when you enable liveconfig settings for the Oracle ATG Web Commerce platform, the defaultGrantAccess property is set to false. Note, however, that this means that each of your Web Services must have an associated security configuration, because any call to a service without a security configuration will fail. For information about enabling liveconfig settings, see the ATG Installation and Configuration Guide.
NucleusSecurityRepository
Web Service security configurations are stored in the NucleusSecurityRepository. This repository includes a single item descriptor called nucleusSecurity, which has properties called functionalName, policy, and ACL. The NucleusSecurityManager parses the items in this repository at startup time.
14
The Web Services Administration interface provides an easy way to add new security configurations to this repository. See the next section for details.
Creating and Editing Security Configurations

The Web Services Administration page in the Dynamo Administration UI includes a Web Service Security Manager link that takes you to a page that where you can view and edit the security configurations stored in the NucleusSecurityRepository, or create new security configurations. Follow these steps to create a new security configuration: 1. Click the Create New link. 2. On the Create Security Configuration page, enter a name for the security configuration in the Functional Name field, and click Create New button. 3. On the Edit Web Service Security Configuration page, click the Add buttons to add users, roles, and organizations to the security configuration. You can change the security policy (from the /atg/dynamo/ security/SecurityPolicy default) if necessary. The new security configuration appears on the main Web Service Security Configurations page. If you need to make changes to it, click the Edit link to open the Edit Web Service Security Configuration page. Note that you cannot change the functional name.
Deploying Web Services

When you create a Web Service, the wizard places the EAR file in the <ATG10dir>/home directory. The Web Service is not ready to run, however, because it does not include the necessary Nucleus classes. In order to run the Web Service, these additional steps are necessary: 1. Use the runAssembler command to assemble a Nucleus-based application, using the -add-ear-file flag to incorporate the contents of the Web Services EAR file. 2. Deploy the assembled EAR file on your application server, and start up the application. For example, if your Web Services EAR file is called WS.ear, you might use a command like this to assemble a Nucleus-based application named MyApp.ear:
runAssembler -add-ear-file WS.ear MyApp.ear -m MyApp DSS
If you make any subsequent changes to the Web Service, you must reassemble and redeploy the application for the changes to take effect. Note that in addition to any Web Services you create, the Oracle ATG Web Commerce platform includes a number of prepackaged Web Services. These services are packaged in three separate application modules. You can include any of these services in an assembled EAR file by including the module that contains the desired services. For example, to include the prepackaged Commerce Web Services, specify the DCS.WebServices module when you assemble your application.
15
For more information about the runAssembler command, see the ATG Platform Programming Guide. For information about deploying EAR files, see the documentation from your application server vendor.
Managing Web Services

The Dynamo Administration UI provides a facility for managing the Web Services deployed on your server. To access this facility, open the top-level page of the Dynamo Administration UI and click the Web Service Administration link. On the Web Service Administration page, click the Web Service Registry link. This takes you to the page for the /atg/webservice/WebServiceRegistry component, which stores information about the available Web Services. For example, if the Web Services included with ATG Commerce are running on your Dynamo server, the top of the page will look similar to this:
The Service Info indicates that there are six Web applications running that include Web Services. You can get more information about the services in a Web application by clicking the details link next to the applications name. For example, if you click on the link for the Pricing application, the Service Info looks like this:
16
The lower table summarizes the status of the Web Services in the Web application. The Name and URI Pattern are the values of the display-name and url-pattern tags in the web.xml file, and the WSDL file is the value of the wsdl.location property in the configuration file for the JAXRPCServlet. The Security functional name is the name that the service implementation class passes to the hasAccess() method of the NucleusSecurityManager to determine if the client has permission to call the Web Service. Some of the information shown in this table, such as the functional name, does not appear until the Web Service has been executed. If a service has been executed, the Instance Running and Registered value is true. You can stop a running service by clicking the Off link in the Enabled column.
Registering Services
Web Services generated by the Web Service Creation Wizard have the necessary code and configuration information to register the Web Service with the Web Service Registry. To register the service, the service implementation class extends the class atg.webservice.ManagedComponentProperties, which includes a register() method for registering the service. In addition, the web.xml file for the Web application the service is part of declares the WebServiceRegistrar servlet, as described in the Web Service Registrar (page 12) section.
17
18
Creating JMS Web Services
In addition to Web Services that call Nucleus methods, the Oracle ATG Web Commerce platform enables you to create Web Services that send JMS messages through Patch Bay. Many events in the Oracle ATG Web Commerce platform are triggered by JMS messages, so by calling a Web Service that sends a JMS message, a client can start execution of various services and processes. In particular, scenario actions are triggered by JMS messages, so you can use Web Service calls to invoke scenario actions remotely. For example, suppose a new user registers in some application, which invokes a Web Service that sends the registration information to the Oracle ATG Web Commerce platform. The client application could then call a Web Service that sends a JMS message of type atg.dps.Register into Patch Bay, thereby triggering a scenario action that (for instance) sends an e-mail message to the new user. This chapter discusses how to create Web Services that send JMS messages, and how to configure components to listen for these messages. For more information about JMS and Patch Bay, see the Dynamo Message System chapter of the ATG Platform Programming Guide.
Using the JMS Message Web Service Wizard

To create a Web Service that sends a JMS message, you use the Web Service Creation Wizard, just as you do for Web Services that invoke Nucleus methods. On the first screen of the wizard, however, you click the JMS Message Web Service link (rather than the Component Method Web Service link). In this version of the wizard, you do not select a Nucleus component and method; instead, the key selections are the message type and the Patch Bay port name to use. The message type is the JMSType value for the message. This is a String, stored in the messages header, that identifies the kind of message it is. For example, a message of JMSType atg.dps.PageVisit is sent when a site visitor displays a page. For the port name, the wizard gives you two options, IndividualEvents and GlobalEvents. These are the standard ports where the Scenario Manager listens for scenario events. The names of the classes generated by the wizard are based on the JMS message type of the message. For example, if you create a Web Service that sends a message whose JMSType is atg.dps.PageVisit, the service implementation interface is named SendPageVisitSEI, and the service implementation class is named SendPageVisitSEIImpl.
3 Creating JMS Web Services
19
Structure of a JMS Web Service

JMS Web Services generated by the wizard are similar to Web Services that call Nucleus methods. JMS services expose a Nucleus method, but it is always the receiveObjectMessage() method of the component /atg/ dynamo/messaging/MessageImporter. This method receives the message object and forwards it into Patch Bay. The receiveObjectMessage() method takes three parameters: the message object a String indicating the JMSType of the message a String indicating the Patch Bay port name to use The Web Service call itself takes only a single argument, the message object. The JMSType and port name are hard-coded when you generate the Web Service, and the service implementation class passes them (along with the message object supplied by the client) to the receiveObjectMessage() method. This simplifies the clients task, because it does not need to be aware of either the JMSType or the port name. For example, a Web Service that sends a JMS message when a user views a page would be called like this:
public void sendPageVisit(atg.userprofiling.dms.PageVisitMessage a);
The service implementation class then calls the receiveObjectMessage() method like this:
messageImporter.receiveObjectMessage(a, "atg.dps.PageVisit", "IndividualEvents");
For information about calling Web Services that send JMS messages from Java clients, see the Accessing ATG Web Services from Java Clients (page 43) chapter. (Note that you cannot use the dynamic process described in that chapter for calling these Web Services.) For information about calling Web Services that send JMS messages from .NET clients, see the Accessing ATG Web Services from .NET Clients (page 55) chapter.
Patch Bay Configuration

The /atg/dynamo/messaging/MessageImporter component, whose receiveObjectMessage() method is invoked by JMS Web Services, is a Patch Bay message source. When a Web Service invokes the method, the message passed to that method is sent either to the destination patchbay:/sqldms/MessageImporter/ IndividualEvents or to patchbay:/sqldms/MessageImporter/CollectiveEvents, depending on the message type. The standard Patch Bay configuration file, /atg/dynamo/messaging/dynamoMessagingSystem.xml, includes the necessary declarations for the message source and destinations:
<message-source> <nucleus-name> /atg/dynamo/messaging/MessageImporter
20
</nucleus-name> <output-port> <port-name> IndividualEvents </port-name> <output-destination> <destination-name> patchbay:/sqldms/MessageImporter/IndividualEvents </destination-name> <destination-type> Topic </destination-type> </output-destination> </output-port> <output-port> <port-name> GlobalEvents </port-name> <output-destination> <destination-name> patchbay:/sqldms/MessageImporter/CollectiveEvents </destination-name> <destination-type> Queue </destination-type> </output-destination> </output-port> </message-source>
The Scenario Manager is a message sink configured to receive messages from these destinations. This configuration occurs in two places: In the standard Patch Bay configuration file, the Scenario Manager is configured to receive individual scenario events from the destination patchbay:/sqldms/MessageImporter/IndividualEvents. In the /atg/dynamo/messaging/dynamoMessagingSystemDSSGlobal.xml file, the Scenario Manager is configured to receive global scenario events from the destination patchbay:/sqldms/MessageImporter/ CollectiveEvents. You can configure other message sinks to receive messages from the patchbay:/sqldms/MessageImporter/ IndividualEvents destination by declaring them in the dynamoMessagingSystem.xml file. Note, however, that you cannot configure other sinks to receive messages from patchbay:/sqldms/MessageImporter/ CollectiveEvents. This destination is a queue, used by global Scenario Managers only; adding sinks to this destination may interfere with the global Scenario Managers receiving messages. If you want another message sink to receive these messages, configure an additional destination for MessageImporter to send global scenario events to, and configure your sink to listen to that destination instead.
21
22
Creating Repository Web Services
The ATG Dynamo Administration interface provides an easy, browser-based way to create Web Services based on repository items. This Repository Web Service wizard is part of the Web Service Administration user interface, which is introduced in the Web Service Creation Wizard (page 7) section of the Creating Custom Web Services (page 5) chapter. You can use the Repository Web Service wizard to create Web Services that add, remove, update, or get a complete repository item, or a single property of a repository item.
Using the Repository Web Service Wizard

To use the Repository Web Service wizard to create a repository Web Service: 1. Open the ATG Dynamo Administration interface and navigate to the Web Service Administration > Web Service Creation Wizard > Repository Web Service page. 2. Identify the repository component that the Web Service should access. You can do this in one of two ways. The Create Repository Web Service page displays a text field in which you can enter the Nucleus address of the repository component and click the Submit button. The Create Repository Web Service page also displays a list of all repository components that are registered in the initialRepositories property of the /atg/registry/ContentRepositories component. You can select a repository component by clicking the link with the Nucleus address of the repository component. 3. The next page, with the heading Select item descriptor, displays all of the item descriptors in the repository component you selected. Click the link for the item descriptor you want to expose in your Web Service. 4. The next page, with the heading Select Method, displays the methods that are available for the item descriptor you selected. For example, if the item descriptor is mutable, the following methods are available:
add remove update get
The Select Method page also allows you to create a Web Service for a specific property. The page displays a list of links for each of the properties of the item descriptor you selected. Click one of these property names to create a Web Service for an individual repository item property. The property name link leads to a list of the Web Service methods that are available for that repository item property, as well as notes about the Web Service limitations, if any, related to the repository item property. See Repository Web Service Limitations (page 24) for more information. Click the name of the method you want to expose in your Web Service.
4 Creating Repository Web Services
23
5. In the EAR Name & Servlet Settings page, the Web Service Creation Wizard displays default names for the EAR file and servlet to be created. You can modify the default names. You can also, if you choose, enter a description for the servlet and a network hostname and port number for the Web Service. If you leave the fields blank, the values are dynamically assigned at runtime from the URL used for the WSDL file request. You should generally leave these fields blank, unless you want to require the Web Service to be accessed on a specific server and port. Enter any settings you want to change and click the Next button. 6. In the Enterprise & Web Application Settings page, the Web Service Creation Wizard displays default names for the enterprise application and Web application to be created. You can modify the default names. You can also, if you choose, enter a description for the enterprise application and Web application. Enter any settings you want to change and click the Next button. 7. The Session & Security Options page allows you to select one of the following three options for the Web Service: 8. Provide neither a session nor security constraints. 9. Provide a session, but no security constraints. 10.Provide both a session and security constraints. If you choose the last option, the wizard then prompts you to select a security configuration. See the Creating Custom Web Services (page 5) chapter for information about security configurations for Web Services. 11.The Create EAR File page displays the parameter values you have selected for your Web Service. Review them, then click the Create EAR File button to create the Web Service. The Web Service is created in an EAR file. You will find the EAR file in the <ATG10dir>/home directory, with the name you selected in step 4. To use the new Web Service, you need to deploy it. See Deploying Web Services (page 15) in the Creating Web Services chapter.
Repository Web Service Limitations

Because of the limitations inherent in Web Services, repository items must generally be passed in XML form. See the Repository to XML Data Binding (page 27) chapter for information about transforming repository items into XML files and vice versa. In particular, you should bear in mind the following restrictions when you are creating repository Web Services:
get/setPropertyValue
1. Collection properties may not be set or gotten as a whole. Only elements of the collection may be set. 2. RepositoryItem properties are set or gotten as Strings in XML form 3. There is no type of service that can get or set sub-properties. You must act upon the actual RepositoryItem you wish to read from or write to. 4. You cannot get or remove elements from a set or list. This is because in order to remove elements from either, you need to provide the object to remove (or index, see below), and a Web Service cannot guarantee that that object is of a type that can be transformed from XML into a Java object.
24
5. You cannot get or set a property of a type that corresponds to a Java primitive. For example, you cannot get or set a java.lang.Integer or a java.lang.Boolean. 6. You cannot get or set a property of a non-simple type, other than atg.repository.RepositoryItem. This includes types such as java.util.Timestamp and java.sql.Date. Note, however, that if you retrieve a Date property, a java.util.Calendar will be returned. 7. You cannot get a property that is not readable, or set a property that is not writable.
addItem
The item to be added must be supplied in XML form.
updateItem
1. The item to be updated must be supplied in XML form. 2. By default, when a repository item is passed into the Web Service, the existing RepositoryItem is found by matching repository IDs. We determine the value of the repository ID from the top-level XML element in the instance document, and then find a repository item with a matching ID.
removeItem
Users must pass in only the repository ID of the item to be removed.
Modifying Repository Web Services

Note that when you create a repository Web Service using the Web Service Creation Wizard, the component path of the repository, the item descriptor name and, if applicable, the property name, are all hardcoded in the generated Web Service. If any of these variables is changed, the Web Service will need to be regenerated. Please note that the repository name is not taken into consideration when naming the Web Service. Only the item descriptor name and, if applicable, property name, is used to name a service. This means that if you are generating Web Services for two or more repositories with the same item descriptor names, you should consider placing them into different WAR files, or giving them different servlet URLs.
RepositoryService Class
The atg.repository.RepositoryService class contains many methods that perform basic Repository operations, independent of any particular repository implementation or instance. Such operations include getting, adding, removing and updating a repository item, setting and getting properties of repository items, and performing queries for repository items using RQL. Using the Web Service generator, you can directly make some of these methods into Web Services by simply clicking a form submit button. Some others of these methods are too generic to be made available as a Web Service without limiting the types of the inputs or outputs. For example, the method setPropertyValue takes a java.lang.Object as a method argument for the property value. Since Web Services dont allow java.lang.Object as an input (or output), this method cannot be used as a Web Service in this form. However, we can restrict the type of this
25
argument using the code generator template functionality, so when the Web Service is generated, the outwardfacing method will be strongly typed based on the property being set, and can simply call through to the more generic setPropertyValue method in the body of the Web Service. The RepositoryService class has the following properties:
Property Name transactionManager
Type
javax.transaction. TransactionManager
Description The service that manages any transactions that are used to execute repository methods on this instance. The component that manages mapping files based on repository and item descriptor name combinations. For any methods that return a RepositoryItem, this service will be consulted to retrieve mapping files to use when transforming these items into XML. See Mapping Files and XML Schemas (page 27) in the Repository to XML Data Binding chapter for more information abut mapping files and the
ItemDescriptorMappingManager
mappingManager
atg.repository.xml. ItemDescriptorMappingManager
class. xmlGetService
atg.repository.xml. GetService atg.repository.xml. AddService
The service that knows how to turn RepositoryItems into XML. The service that knows how to add RepositoryItems in XML format to a repository. The service that knows how to take RepositoryItems in XML format and update them in their corresponding repositories.
xmlAddService
xmlUpdateService
atg.repository.xml. UpdateService
For information about the XML service properties, see Repository Operations (page 35) in the Repository to XML Data Binding chapter.
26
Repository to XML Data Binding
One of the key aspects of integrating the Oracle ATG Web Commerce platform with a remote system is sharing data between the two systems. Data sharing and synchronization are often complex, because the two systems may store their data in dissimilar formats. The Oracle ATG Web Commerce platform data is typically stored in a Dynamo repository, which handles the mapping of data in Java objects to the underlying data store (such as a SQL database). The Oracle ATG Web Commerce Integration Framework includes a data binding facility for reading and writing data between a repository and XML documents. Using this facility, you can write out repository data to XML documents that can then be read into a remote system, or read data into a repository from XML documents that store data from a remote system. A key aspect of this system is the use of mapping files to specify the data to include or exclude, and to map the names of repository properties to the names used by the remote system. The data binding facility also includes tools for generating XML Schemas that describe the structure of data in a repository, and to use these XML Schemas to validate the data written out from or read into the repository. The data binding facility provides services that perform these four operations with repository items: Getting items (retrieving items from a repository and writing them out to XML documents) Adding items (creating new items in a repository from data in XML documents) Updating items (modifying existing items using data in XML documents) Removing items (deleting items as indicated in XML documents) This chapter discusses: Mapping Files and XML Schemas (page 27) Repository Operations (page 35) Note that the classes described in this chapter work only with repositories included in the initialRepositories property of the /atg/registry/ContentRepositories component.
Mapping Files and XML Schemas

In addition to the XML instance documents that store the actual data, data binding uses two other types of documents: Mapping files control which data is exchanged between system, and which data is omitted.
5 Repository to XML Data Binding
27
XML Schemas describe the structure of the data, and can be used to validate XML instance documents.
Mapping Files
When you exchange data between the Oracle ATG Web Commerce platform and a remote system, you will typically want to exclude certain data. For example, an the Oracle ATG Web Commerce platform profile usually includes Dynamo-specific information about scenarios. When you create an XML instance document from data in a repository, Dynamo includes and excludes certain properties by default: If a property is readable and does not point to another item descriptor, it is included. If a property is readable, points to another item descriptor, and its cascade attribute is set to "delete", it is included. All other properties are excluded. For more information about the default inclusion rules, see the isIncludeProperty() method of the atg.repository.xml.RepositoryXMLTools class in the ATG Platform API Reference. RepositoryXMLTools is a utilities class with various methods for encoding and decoding item descriptors, property names, and mapping files to and from XML-compatible namespaces and identifiers. If you want more explicit control over the properties that are written out, you can use a mapping file. A mapping file specifies what properties to include or exclude when moving data between a repository and an XML instance document, and provides a way to map the names of Dynamo properties to their equivalents in a remote system. For example, a Dynamo profile might have an email property that stores the same information as the Email_Address attribute on another system. The following is the Document Type Definition (DTD) for mapping files:
<!-This is the XML DTD for ItemDescriptorMapping --> <!-Specifies what properties in an item-descriptor should be included in another datamodel. A given mapping file gives the ability to - control what properties are included/excluded from the datamodel - control how names in one model relate to names in another model --> <!-Defines the mapping for a given item-descriptor. The name and repository property are required properties. The name property corresponds to the name of a given item-descriptor. The repository should be the Nucleus path to a particular repository. For example, if an item-descriptor mapping was going to point to the the ProfileAdapterRepository located at /atg/userprofiling/ProfileAdapterRepository Nucleus path, then the repository property should be the string "/atg/userprofiling/ProfileAdapterRepository". The default-include exists to indicate whether or not properties that are associated with this item-descriptor should be included by default or not. This property defaults to true. So, if a property is does not explicitly
28
appear as a child property element, it is assumed to be included in the data model to be exported. --> <!ELEMENT item-descriptor (property*)> <!ATTLIST item-descriptor repository-path CDATA #IMPLIED name CDATA #IMPLIED default-include (true | false) #IMPLIED> <!-A property element controls two aspects of including a property in a given mapping; whether the property should be included or not and what the targetName for the target datamodel should be. The name attribute corresponds to the name of a property defined for a given item-descriptor. The include attribute is optional. If it is not specified, the value is obtained from the default-include value of the enclosing item-descriptor. --> <!ELEMENT property (item-descriptor*)> <!ATTLIST property name CDATA #REQUIRED include (true | false) #IMPLIED targetName CDATA #IMPLIED>
Sample Mapping File

The following is a sample mapping file for the Dynamo profile repository:
<!DOCTYPE item-descriptor SYSTEM "http://www.atg.com/dtds/databinding/itemDescriptorMapping_1.0.dtd"> <item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="user" default-include="true"> <property name="homeAddress" include="true"> <item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="contactInfo" default-include="false"> </item-descriptor> </property> <property name="slotInstances" include="false"/> <property name="scenarioInstances" include="false"/> <property name="mailings" include="false"/> <property name="scenarioValues" include="false"/> <property name="firstName" targetName="first_name"/> </item-descriptor>
The data binding services all work with a single item descriptor and its properties (including any other item descriptors that are properties of the main item descriptor). The mapping file uses the item-descriptor tag to specify the repository and item descriptor that the mapping file is associated with:
<item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="user"
29
default-include="true">
The default-include attribute specifies whether the items properties should be included or excluded by default. This value can be overridden for individual properties. In this mapping file, various scenario-related properties are excluded:
<property <property <property <property
name="slotInstances" include="false"/> name="scenarioInstances" include="false"/> name="mailings" include="false"/> name="scenarioValues" include="false"/>
If a property is an item descriptor, there must be an item-descriptor tag inside the property tag. For example, the homeAddress property points to a contactInfo item descriptor:
<property name="homeAddress" include="true"> <item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="contactInfo" default-include="false"> </item-descriptor> </property>
Note that the item-descriptor tag for contactInfo can have property tags within it. The nesting of property tags and item-descriptor tags must reflect the hierarchy of the item descriptors in the repository. If you do not include a property tag for a property that points to an item descriptor (such as the homeAddress property shown above), the Oracle ATG Web Commerce platform uses the default inclusion rules for determining which properties of that item descriptor to include. Finally, the property tag has an optional targetName attribute for mapping the property name to its corresponding name in the remote system:
<property name="firstName" targetName="first_name"/>
Managing Mapping Files for Repository Item Descriptors

The Oracle ATG Web Commerce platform includes two classes that help identify the appropriate mapping file for each item descriptor that you want to use with the repository2xml data binding facility. These classes are used by Web Service clients:
atg.repository.xml.ItemDescriptorMapping atg.repository.xml.ItemDescriptorMappingManager
ItemDescriptorMapping
An ItemDescriptorMapping is a simple bean that holds information about relationships between repository item descriptors and mapping files. The mapping files describe what properties are to be exposed when an item from that item descriptor is to be transformed into XML. Each ItemDescriptorMapping pertains to exactly one repository: for example, you would have a UserProfileItemDescriptorMapping, or a
30
PromotionItemDescriptorMapping component, each of which would provide a list of item descriptor names
from the corresponding repository and their corresponding mapping files. An ItemDescriptorMapping contains only three properties:
Property Name
repositoryPath
Type
java.lang.String
Description The path to the repository supported by this

ItemDescriptorMapping. This is a
read-only property
repository atg.repository.Repository
The path to the repository supported by this

ItemDescriptorMapping. Similar to repositoryPath but
this property will resolve to an actual Repository instance, and is writeable.

itemDescriptorMapping java.util.Map
A map where the keys are item descriptor names and the values are locations of mapping files, relative to the configuration path, which provide rules for how an item of the keyed item descriptor name appears in XML format
Here is an example properties file for an ItemDescriptorMapping that supports the profile repository:
$class=atg.repository.xml.ItemDescriptorMapping repository=/atg/userprofiling/ProfileAdapterRepository itemDescriptorMapping=\ user=/atg/userprofiling/userMapping.xml,\ contactInfo=/atg/userprofiling/contactInfoMapping.xml
Here we see the there are two entries in the itemDescriptorMapping property, one for the user item descriptor, and one for the contactInfo item descriptor. Whenever an entry is added to the itemDescriptorMapping property, whether through a properties file, or directly in code, the ItemDescriptorMapping checks to make sure that the key of the entry, the item descriptor name, resolves to an actual item descriptor of the repository this service is configured to support. If any item descriptor name does not resolve, a RepositoryException is thrown. By themselves, ItemDescriptorMappings dont do any work. They simply hold state. In order to put them to work, you must add them to the ItemDescriptorMappingManager, described below.
ItemDescriptorMappingManager
Class: atg.repository.xml.ItemDescriptorMappingManager Component: /atg/repository/xml/ItemDescriptorMappingManager
31
Module: DAS The ItemDescriptorMappingManager serves as a registry of ItemDescriptorMappings. It is through this service that you obtain mapping files for all repository and item descriptor combinations. The mapping files are registered in the itemDescriptorMappings property of the ItemDescriptorMappingManager component:
Property Name
itemDescriptorMappings
Type
atg.repository.xml. ItemDescriptorMapping[]
Description An array of
ItemDescriptorMapping
components. When a user calls methods to retrieve mapping files, this component sifts through the itemDescriptorMappings to determine the correct mapping.
Here is an example properties file:

$class=atg.repository.xml.ItemDescriptorMappingManager itemDescriptorMappings=\ /atg/userprofiling/UserProfileItemMapping,\ /atg/userprofiling/ContactInfoItemMapping
The following ItemDescriptorMappingManager methods can be used to retrieve mapping files:

getMappingFileName(String pRepositoryPath, String pItemDescriptorName)
Using the given repository path and item descriptor name, returns the mapping file for that given path:name combination, or null if none exists.
getMappingFileName(Repository pRepository, String pItemDescriptorName)
Using the given repository and item descriptor name, returns the mapping file for that given repository:name combination, or null if none exists. When you use the atg.repository.xml.GetService to get repository items in XML form, you can pass along a mapping file name using these ItemDescriptorMappingManager methods. Using the ItemDescriptorMappingManager, you can centralize all mapping files in one component for all item descriptors, and just call that to determine which mapping file to use for a given item descriptor.
XML Schemas
The Oracle ATG Web Commerce platform provides tools for creating and working with XML Schemas for the XML documents written and read by the various data binding services. XML Schema is a schema language for XML that describes and restricts what a particular XML instance document might look like. An XML document can be validated against an XML Schema to check that it conforms to that Schema. Additionally, many developer tools make use of XML Schemas. For example, some tools provide a visual representation of XML Schemas to allow mapping from one XML Schema to another.
Generating XML Schemas

The Oracle ATG Web Commerce platform provides a command-line tool that generates an XML Schema for a given item descriptor. The XML generated by the Get data binding service conforms to this Schema. Similarly,
32
the XML Schema describes an instance document that is capable of being processed by the Add, Update, or Remove service. The command-line tool is named generateXMLSchema.sh (on Unix) or generateXMLSchema.bat (on Windows) and is found in the <ATG10dir>/home/bin directory. The following table lists the arguments that can be supplied to this command:
-repository
Nucleus path to the repository containing the item descriptor that the XML Schema is being generated for. Required. Name of the item-descriptor that the XML Schema is being generated for. Required. Specifies a directory to save the XML Schema to. This directory is in addition to the directory specified by the XMLSchemaFileDirectory property of the XMLSchemaManager. Not required. If set to true, then the Schemas will be saved via the configured XMLSchemaManager. If omitted, defaults to true. Specifies the mapping file to use. Not required. Nucleus path to the Schema Generator component. If omitted, defaults to /atg/ repository/xml/SchemaGenerator. Specifies the set of modules to use in the repository definition. Required. Prints out a usage message. Not required.
-itemDescriptor
-outputDirectory
-saveSchemas
-mappingFile -schemaGenerator
-m -help
Example
The following command generates an XML Schema for the user item descriptor of the default Dynamo profile repository, using the properties defined in the repository definition file for the DSSJ2EEDemo application module (and the modules required by the DSSJ2EEDemo module):
generateXMLSchema -m DSSJ2EEDemo repository /atg/userprofiling/ProfileAdapterRepository -itemDescriptor user
The generated XML Schema is saved by the Schema Manager specified by the schemaManager property of the Schema Generator component. The default Schema Generator is the /atg/repository/xml/ SchemaGenerator component, and its schemaManager property points by default to the /atg/repository/ xml/SchemaManager component. Note that if the user item descriptor contains other item descriptors as properties, the generated Schema will reflect these other item descriptors as well. To save the Schema to the current working directory in addition to the directory determined by the XMLSchemaFileDirectory property of the Schema Manager:
generateXMLSchema -m DSSJ2EEDemo repository /atg/userprofiling/ProfileAdapterRepository -itemDescriptor user -outputDirectory .
33
Managing Schemas and Mapping Files

As mentioned above, the default Schema Generator has a schemaManager property that points to the /atg/repository/xml/SchemaManager component. In addition, each of the data binding service components (described below) has an XMLSchemaManager property that points to this SchemaManager component. This component is of class atg.repository.xml.XMLSchemaManager. This class, which extends atg.repository.databinding.MappingManager, manages XML Schemas and mapping files. For example, this class has mappingFileDirectories and XMLSchemaFileDirectory properties that specify the directories where mapping files and Schemas are stored. Note that Schemas must have the extension .xsd and mapping files must have the extension .xml. For example, suppose you want to generate an XML Schema and specify a mapping file to use. The command would look something like this:
generateXMLSchema -m DSSJ2EEDemo repository /atg/userprofiling/ProfileAdapterRepository -itemDescriptor user -mappingFile profileMapping.xml
Notice that only the name of the mapping file is specified, not the entire pathname. The Schema Managers mappingFileDirectories property points to the directories where the mapping file should be stored.
PropertyElementNameSeparator
The repository2xml feature specifies a separator character, which functions to separate a property name from the name of its item descriptor. By default, this separator character is . (dot). The default separator character may not work for you if, for example, you use composite repository IDs that also use the . (dot) character to separate elements of the repository ID. You can specify a different separator character in the propertyElementNameSeparator property of the /atg/repository/xml/RepositoryXMLTools component.
Item References
In a repository schema, a map, set, list, or array property can point to a single other item using the itemRef attribute. The value assigned to the itemRef attribute concatenates the item descriptor name, the property element separator, and the repository ID. In the following example, the item descriptor name is role, the property element separator is . (dot) and the repository ID is 2900004:
<user:itemRef itemRef="role.2900004"/>
The following is a more extended example, showing the context for the itemRef attribute:
<user:user xmlns:user=http://www.atg.com/ns/profileMapping/UserProfiles/user xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:schemaLocation="http://www.atg.com/ns/profileMapping/UserProfiles/user profileMapping+UserProfiles+user.xsd " ID="user747"> <user:homeAddress itemRef="contactInfo.1040001"/> <user:roles> <user:itemRef itemRef="role.2900004"/> <user:itemRef itemRef="role.3000008"/> </user:roles>
34
</user:user>
Repository Operations
The atg.repository.xml package includes a service class for each of the four repository operations supported by the data binding facility. The following table lists these classes and the Nucleus instances included in Dynamo:
Class
atg.repository.xml.GetService atg.repository.xml.AddService atg.repository.xml.UpdateService atg.repository.xml.RemoveService
Nucleus component
/atg/repository/xml/GetService /atg/repository/xml/AddService /atg/repository/xml/UpdateService /atg/repository/xml/RemoveService
The following sections discuss each of these classes and the operations they perform. See the entries for these classes in the ATG Platform API Reference for more information.
Getting Repository Items

You use getItemAsXML() method of the atg.repository.xml.GetService class to create XML documents from repository items. This method takes a repository item as an input argument and returns a String containing an XML representation of this item. If you write out this String (e.g., to a file), be sure to use the same character encoding that the repository uses. Some versions of the getItemAsXML() method take additional inputs for specifying a String array of the names of the properties to write out or a String containing the name of the mapping file to use. If you supply only a repository item as input, the method uses the default inclusion rules (described in the Mapping Files (page 28) section) to determine which properties to include. By default, GetService writes out an XML document as a single line, because it is intended to be machinereadable. If you want the generated XML to be human-readable, set the indentXMLOutput property of the GetService component to true. The resulting XML will have appropriate line breaks.
Example
Suppose you want to generate XML for a user profile, based on a mapping file named profileMapping.xml. The following code finds the user repository item whose ID is "user747" and generates an XML representation of it:
RepositoryItem userItem = getProfileRepository().getItem("user747", "user"); String userAsXML = GetService.getItemAsXML(userItem,"profileMapping.xml");
35
The following is sample output from this code. The data represents the profile of the user sandy in the Quincy Funds demo:
<user:user xmlns:user="http://www.atg.com/ns/profileMapping/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/profileMapping/UserProfiles/user profileMapping+UserProfiles+user.xsd " ID="user747"> <user:securityStatus>0</user:securityStatus> <user:actualGoals>long-term</user:actualGoals> <user:gender>female</user:gender> <user:fundShares> <user:integer>500</user:integer> <user:integer>220</user:integer> <user:integer>180</user:integer> <user:integer>260</user:integer> </user:fundShares> <user:goals>short-term</user:goals> <user:dateOfBirth>1976-12-09</user:dateOfBirth> <user:pubPrivileges>none</user:pubPrivileges> <user:homeAddress> <user:homeAddresscontactInfo ID="contactInfo747"/> </user:homeAddress> <user:numberNewsItems>4</user:numberNewsItems> <user:strategy>conservative</user:strategy> <user:locale>en_US</user:locale> <user:lastActivity>2002-08-14T18:33:49.604</user:lastActivity> <user:aggressiveIndex>5</user:aggressiveIndex> <user:lastName>Pieta</user:lastName> <user:actualStrategy>conservative</user:actualStrategy> <user:interests> <user:string>tax</user:string> <user:string>international</user:string> </user:interests> <user:id>747</user:id> <user:fundList> <user:string>/repositories/Funds/en_US/overseas.xml</user:string> <user:string>/repositories/Funds/en_US/moneymarket.xml</user:string> <user:string>/repositories/Funds/en_US/growth.xml</user:string> <user:string>/repositories/Funds/en_US/growthincome.xml</user:string> </user:fundList> <user:email>sandy@example.com</user:email> <user:password>d686a53fb86a6c31fa6faa1d9333267e</user:password> <user:registrationDate>1999-04-15T00:00:00.0</user:registrationDate> <user:userType>investor</user:userType> <user:member>true</user:member> <user:brokerId>734</user:brokerId> <user:numberFeatureItems>3</user:numberFeatureItems> <user:login>sandy</user:login> <user:guests>false</user:guests> <user:brokers>false</user:brokers> <user:investors>true</user:investors> </user:user>
Namespaces
Notice that information about the XML Schema for this data is included in the user:user tag at the beginning of the document:
36
xsi:schemaLocation="http://www.atg.com/ns/profileMapping/UserProfiles/user profileMapping+UserProfiles+user.xsd "
The xsi:schemaLocation attribute specifies the URL and name of the Schema file. The Schema filename (profileMapping+UserProfiles+user.xsd) is determined by the name of the mapping file (profileMapping.xml), the name of the repository (UserProfiles), and the item descriptor (user). If no mapping file is used to create the document, the Schema filename indicates the repository and item descriptor. If you want the Schema filename to include the entire pathname, set the appendRelativeSchemaLocation property of the GetService component to true. This is especially important if youre using an external Schema verification tool, which will generally need the complete pathname to find the Schema file. If you use a mapping file when you create an instance document, you should be sure to supply the name of this mapping file to the generateXMLSchema command (using the mappingFile argument) when you generate the Schema. Otherwise the actual Schema filename will not match the name in the xsi:schemaLocation tag, and the Schema may not accurately reflect the data in the instance document; as a result, you may not be able to validate the data when reading it into a remote system (or reading it back into Dynamo using AddService). Note also that if your call to getItemAsXML() includes an input argument that specifies the names of properties to write out, the Schema will not accurately reflect the data in the instance document, so validation will not be possible. To avoid any conflict between tag names, the XML tags in the generated instance document are named using the convention itemType:propertyName; for example the user:userType tag stores the value of the userType property of the user item type. If the addItemTypeToPropertyNames property of the RepositoryXMLTools component that GetService points to is set to true, the tags are named using the convention itemType:itemType.propertyName; in this case, the tag name would be user:user.userType. By default addItemTypeToPropertyNames is set to true, because the resulting XML is less likely to result in naming collisions.
Adding Repository Items

You use the addItem() method of the atg.repository.xml.AddService class to create new repository items from XML documents. This method takes an XML document as an input argument and returns a repository item. The XML document can be in the form of a String, a java.io.Reader, or a java.io.InputStream. The method examines the schemaLocation attribute in the XML document to determine if there is a mapping file associated with the document. Some versions of the method take additional arguments for specifying how to handle missing or empty tags, and whether the data should be validated against a Schema. For some examples of how a repository item might look in XML document form, see the <ATG10dir>/ RL/Example/j2ee-apps/example/web-app/public directory. The Repository Loader (RL) module also includes a page you can use to generate XML documents from existing repository items. This page is located at <ATG10dir>/RL/Example/j2ee-apps/example/web-app/itemAsXml.jsp. Note that addItem() cannot create new read-only elements in a repository. By default, any data in the instance document that corresponds to a read-only element in the repository is silently ignored. If you want addItem() to log a warning each time it skips a read-only element, set the logWarningOnReadOnly property of the AddService component to true.
Validating the Data

The addItem() method can optionally validate the data in an XML instance document against the Schema specified in the instance document. Validation is enabled or disabled by the validate property of the
37
AddService component. By default, this property is set to false, because validation slows down processing of the document. To enable validation, set the validate property to true.
The addItem() method can also take a Boolean argument to specify whether to validate the document. The value of this argument overrides the validate property. If you do not specify this argument, addItem() uses the validate property to determine whether to validate the document. If you are confident that your data is valid, you can disable validation, and the instance document will be processed more quickly. However, if the data turns out to be invalid, the invalid data may be written to the repository. If you enable validation and the data is invalid, addItem() does not write the contents of the instance document to the repository.
Updating Repository Items

You use the updateItem() method of the atg.repository.xml.UpdateService class to modify a repository item. For example, the following instance document updates a users email address:
<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747"> <user:user.emailAddress>sandy@example.com</user:user.emailAddress> </user:user>
The updateItem() method can optionally validate the instance document against the specified Schema. The logic for this is similar to the AddService.addItem() method: the UpdateService component has a validate property whose default value is false, and the updateItem() method can take a Boolean argument that overrides the value of the validate property.
Selecting the Item to Update

There are two ways to select the item to update: You can specify the item explicitly when you call updateItem(). You can specify a set of match properties, and updateItem() selects the item whose values match the corresponding values in the instance document. For example, the login property is often used for matching, because it is unique to a specific user item and its value does not change. The following XML instance document could be used to select the item and then update its emailAddress property:
<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747"> <user:user.emailAddress>sandy@example.com</user:user.emailAddress> <user:user.login>sandy</user:user.login> </user:user>
The application would then use the following code to update the user repository item whose login value is sandy (assuming the inputXML String contains the instance document shown above):
38
String[] matchProperties = {"login"}; RepositoryItem updatedItem = UpdateService.updateItem(inputXML, matchProperties);
Note that UpdateService determines the repository and item type from the namespace of the instance document. For more information, see Namespaces (page 36) in the Getting Repository Items (page 35) section. The matchProperties array can contain any number of property names. If the value of each repository item property named in matchProperties matches its corresponding attribute in the XML instance document, the item is selected for update. All of the specified properties must match for the item to be selected; for example, if matchProperties lists login and lastName properties, the values of both properties must match. If multiple items are selected, an exception is thrown and no update occurs. Matching is limited to top-level properties of the repository item. Subproperties (such as properties of other repository items) cannot be matched. So, for example, if a user item has a lastName property that is a String, you can include lastName in matchProperties; but if a user item has a shippingAddress property that is another repository item, you cannot include, say, shippingAddress.city in matchProperties. If a property has been mapped to a different name in the instance document, the name to match on is the property name used in the repository, not the instance document. For example, suppose you use a mapping file to map a user items dateOfBirth property to the name birthday, like this:
<item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="user" default-include="true"> <property name="dateOfBirth" targetName="birthday"/>
The corresponding instance document might look like this:
<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747"> <user:user.birthday>02-06-1975</user:user.birthday> </user:user>
To specify this property in matchProperties, you use the name of the property as it is defined in the repository (dateOfBirth), not the target name (birthday). For example:
String[] matchProperties = {"dateOfBirth"};
You can configure the UpdateService to add a repository item if an attempt to update does not find a match. If you want the UpdateService to add items when no items are matched, set the addWhenNoMatchedItems property of the UpdateService to true. If the property being updated is a simple type (such as a String), then its value is updated by the UpdateService. When the property being updated is a list, map or array, then the old value is replaced by the new value. The new value is not appended to the old value. If the property being updated is an item descriptor, then the appropriate fields of the existing item descriptors are updated.
39
repositoryId
The repositoryId attribute of an item can be used as a special match property. If the repositoryId String is passed to UpdateService as a match property, the service will determine the value of this attribute from the top-level XML element in the instance document, and then find a repository item with a matching repository ID. The following XML example uses the repositoryId attribute as a match property:
<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747" repositoryId="user707"> <user:user.emailAddress>sandy@example.com</user:user.emailAddress> </user:user>
String[] matchProperties = {"repositoryId"}; RepositoryItem updatedItem = UpdateService.updateItem(inputXML, matchProperties);
In this case, the UpdateService selects the user item whose repositoryId is "user707" from /atg/ userprofiling/ProfileAdapterRepository. Note: Do not confuse with the repositoryId attribute, which identifies a repository item, with the ID attribute used in the XML schema to identify an XML element. The repositoryId attribute and not the ID attribute is used to identify which repository item to update.
Removing Repository Items

You use the removeItems() method of the atg.repository.xml.RemoveService class to delete repository items specified in XML documents. This method takes an XML document in the form of a String array, a java.io.Reader, or a java.io.inputStream. Some versions of removeItems() take a matchProperties String array. Property matching for RemoveService.removeItems() uses the same logic as UpdateService.updateItem(), except it is legal for multiple repository items to be marked for deletion. For example, an instance document to remove all users whose date of birth is 02-06-1975 would look like:
<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747"> <user:user.dateOfBirth>02-06-1975</user:user.dateOfBirth> </user:user>
The application then uses the following code to remove all the user repository items whose dateOfBirth value is 02-06-1975 (assuming the inputXML String contains the instance document shown above):
String[] matchProperties = {"dateOfBirth"}; String[] removedItemIds = RemoveService.removeItem(inputXML,matchProperties);
40
The maximum number of matching items is specified by the maxSelectedItems property of RemoveService. If the number of matching repository items exceeds this value, an exception is thrown. In the /atg/ repository/xml/RemoveService component, maxSelectedItems is set to 5 by default.
41
42
Accessing ATG Web Services from Java Clients
The Oracle ATG Web Commerce platform permits external Java clients to access Nucleus methods by exposing them as Oracle ATG Web Commerce Web Services. Many such Oracle ATG Web Commerce Web Services are included with the Oracle ATG Web Commerce platform, as are tools for creating custom Web Services. For a list of Oracle ATG Web Commerce Web Services, see ATG Web Services (page 3). Java clients can execute those Web Services through calls that are translated into XML wrapped in SOAP, transmitted to the Oracle ATG Web Commerce platform, and routed to the Nucleus method itself. Other Oracle ATG Web Commerce resources, such as JMS messages and RepositoryItems, can also be exposed as Oracle ATG Web Commerce Web Services. The Oracle ATG Web Commerce implementation of Web Services follows the standard Web Service guidelines outlined by JAX-RPC 1.0 and SOAP 1.1 specifications. You may use Apache Axis 1.4 to create your Web Service calls, and this chapter includes code examples that assume you are using Axis. This chapter aims to inform you how to call Oracle ATG Web Commerce Web Services from an Axis client. Rather than provide a broad discussion on how to use Axis, this chapter describes Oracle ATG Web Commerce-specific features and processes that you need to be familiar with. Please see the Axis documentation for comprehensive instructions. To access an Oracle ATG Web Commerce Web Service, you need to be familiar with the following topics: About ATG Web Services (page 43) Before You Begin Using a Java Client (page 45) Writing a CookieContainer Class (page 45) Calling ATG Web Services from a Java Client (page 47) Creating a Serializer and Deserializer (page 51)
About ATG Web Services

For the most part, you call Oracle ATG Web Commerce Web Services in the same way you call Web Services elsewhere. While the general process may not differ, its important that you are aware of these platform-specific features.
6 Accessing ATG Web Services from Java Clients
43
Security
The content you see as a response to a Web Service call depends on your access privileges. When you login using the loginUser Web Service, you provide your user identity. If session sharing is enabled, all subsequent Web Service calls in that session are associated with that identity and related role. For more information on loginUser, see the ATG Personalization Programming Guide. You may also want to learn how other Web Services handle the security information provided by loginUser. Such information exists in the ATG Repository Guide and the ATG Commerce Programming Guide.
Transactions
When a client calls a Web Service, the transactional behavior of the service is managed entirely on the server side. The method that is exposed as a Web Service can use standard transaction demarcation techniques, but the calling client has no control over this. There are some practical considerations you should be aware of. If a single Web Service call attempts to perform some operation, and the operation fails, the operation can be rolled back (provided that the Nucleus method is demarcated properly). However, a transaction cannot span multiple Web Service calls so if an operation is performed by a sequence of Web Service calls, and the final call fails, there is no way to roll back the steps performed by the previous calls.
Sharing Sessions
When you create a Web Service, you specify whether it should be executed within the context of an HTTP session. Associating Web Services with a session enables an application to maintain state across Web Service calls and to use login information for security purposes. To allow multiple Web Services to share a session, two things need to happen: 1. The Web Service client must allow a session to be shared across certain Web Service calls. To do this, the client must pass a session cookie between calls. 2. The Web Services themselves must support sessions. When you create custom Web Services, the Web Service Creation Wizard gives you the option of supporting sessions. This chapter includes an example of a helper class that you can use to simplify cookie management. See Writing a CookieContainer Class (page 45).
RepositoryItems
If your Web Services access RepositoryItems, you need to provide a serializer and deserializer so the RepositoryItem content can be interpreted by non-Oracle ATG Web Commerce systems. The following Web Services transmit content thats natively stored as RepositoryItems: getProfile getRepositoryItem performRQLQuery getOrderAsXML (Commerce users only) getOrdersAsXML (Commerce users only) getProductXMLById (Commerce users only)
44
getProductXMLByDescription (Commerce users only) getProductXMLByRQL (Commerce users only) getProductSkusXML (Commerce users only) getPromotionsAsXML (Commerce users only) The Oracle ATG Web Commerce platform includes several tools for working with RepositoryItems. To make a client able to serialize and deserialize RepositoryItems, you need to translate the RepositoryItem class into a language thats native to your client. See Creating a Serializer and Deserializer (page 51) for more information.
Before You Begin Using a Java Client

Before you can access a Web Service, you need to make sure the Oracle ATG Web Commerce platform is ready for your call and Axis 1.4 is configured: 1. Confirm that the application that includes the Web Service is deployed on your application server and is running. For more information, see Deploying Web Services (page 15). 2. Download Axis 1.4 from the Apache web site:
http://ws.apache.org/axis
3. Extract the contents of the Axis download file. 4. Add the axis libraries to your CLASSPATH. See the Apache site for more information about using Axis.
Writing a CookieContainer Class

The following example shows a sample CookieContainer class. You can use this as a model for your own class. Note that: This class relies on the Axis API. If you are using a different Java client, you will need to use the API for your client. This class works with both static and dynamic Web Service calls. (See Calling ATG Web Services from a Java Client (page 47).) If you always make only one of these call types, your own CookieContainer class does not need to handle both cases.
package com.example.webservice; import import import import /** org.apache.axis.MessageContext; org.apache.axis.client.Call; org.apache.axis.client.Stub; org.apache.axis.transport.http.HTTPConstants;
45
* A class that can be passed between web service clients that keeps track of * the cookies received from the server. These cookies are then used by * subsequent web service client calls in order to ensure that session * state is maintained. **/ public class CookieContainer { //------------------------------------// Member variables //------------------------------------/** Array of cookies from the Set-Cookie HTTP header **/ private String[] mCookies = null; /** Array of cookies from the Set-Cookie2 HTTP header **/ private String[] mCookies2 = null; //------------------------------------// Methods //------------------------------------/** * Gets the cookies set by the Set-Cookie HTTP header * @return the cookies from the Set-Cookie HTTP header, which * may be null **/ public String[] getCookies() { return mCookies; } /** * Gets the cookies set by the Set-Cookie2 HTTP header * @return the cookies from the Set-Cookie2 HTTP header, which * may be null **/ public String[] getCookies2() { return mCookies2; } /** * Extracts the cookies from the given Axis MessageContext, and * sets the cookies and cookies2 properties from them. * @param pContext the Axis message context to examine. This * cannot be null **/ public void extractCookies(MessageContext pContext) { mCookies = (String[])pContext.getProperty (HTTPConstants.HEADER_COOKIE); mCookies2 = (String[])pContext.getProperty (HTTPConstants.HEADER_COOKIE2); } /** * Extracts the cookies from the given Axis Call, and * sets the cookies and cookies2 properties from them. * @param pCall the Axis call to examine. This * cannot be null **/ public void extractCookies(Call pCall) { extractCookies(pCall.getMessageContext());
46
} /** * Extracts the cookies from the given Axis Stub, and * sets the cookies and cookies2 properties from them. * @param pStub the Axis stub to examine. This * cannot be null **/ public void extractCookies(Stub pStub) { extractCookies(pStub._getCall()); } /** * Pushes the cookie values that are set on the instance to * the given Call * @param pCall the call to set the cookies on. This cannot be null **/ public void pushCookies(Call pCall) { if(mCookies != null) pCall.setProperty(HTTPConstants.HEADER_COOKIE, mCookies); if(mCookies2 != null) pCall.setProperty(HTTPConstants.HEADER_COOKIE2, mCookies2); } /** * Pushes the cookie values that are set on the instance to * the given Stub * @param pStub the stub to set the cookies on. This cannot be null **/ public void pushCookies(Stub pStub) { if(mCookies != null) pStub._setProperty(HTTPConstants.HEADER_COOKIE, mCookies); if(mCookies2 != null) pStub._setProperty(HTTPConstants.HEADER_COOKIE2, mCookies2); } }
Calling ATG Web Services from a Java Client

When you call a Web Service, you create resources that describe the Web Service you want to call, its location, and initial inputs. Axis then takes those resources and produces from them a SOAP message that it then sends to the Web Service itself. There are two ways to create a Web Service call: Use a client stub to create a static Web Service call. Use the Dynamic Invocation Interface to create a dynamic Web Service call. The main distinction between the two processes is the data types they can handle. Because using Web Services requires that data be converted into several formats from a native format into an XML representation of that format back into the native form it is important that you choose a process designed to work with the data types accessed by the Web Services you want to employ.
47
The static process can handle any data type regardless of whether its primitive, complex, object, or nonstandard. Non-standard types may require some extra effort as is the case when accessing Oracle ATG Web Commerce RepositoryItems or JMS messages. The dynamic process, conversely, is limited to only working with object versions of these data types (as permitted by SOAP 1.1): Boolean Byte Double Float Int Long Short Some complex types such as Array, List, Set, and Map may be supported using the dynamic process in a restricted way. See the JAX-RPC Specification for details on data type restrictions. The subsequent sections describe how you would make a call to the loginUser Oracle ATG Web Commerce Web Service following the static and dynamic processes.
Creating a Call Using a Client Stub (Static)

When you create a call following the static method, you represent the server-side Web Service architecture on the client by creating a client stub and a client: The client stub describes the associated Web Services resources as well as the remote procedure call that the Web Service executes. The client configures a particular Web Service instance by specifying initial values and methods on various Web Services resources. The call is constructed by compiling information from the client stub, client, and various other supporting classes that hold static information. For example, to create a static call to the loginUser Web Service: 1. Create and compile the client stub, if one does not already exist for the Web Service. See Creating and Compiling a Client Stub (page 49) below. 2. Add the client stub to the CLASSPATH variable so the client stub is available to local Web Services resources. 3. Create and compile the client. See Creating and Compiling a Client (page 49) below. 4. Use Axis to execute the Web Service call:
loginStub.createUser(pProfileAsXML)
The format of this call is clientStub.web_service(generated_web_Service_Call_instance) Axis creates the XML message, wraps it in SOAP, and sends it via HTTP to the Web Service location in the client stub.
48
Creating and Compiling a Client Stub

The client stub describes the Web Service method and supporting resources in a structure thats familiar to the client. Each Web Service requires a stub for each client that executes it. You can reuse a stub for subsequent calls so you only need to create it once. However, simultaneous calls to a Web Service made by different threads will require that a unique client stub instance exists for each thread. To create and compile a client stub for the loginUser Web Service: 1. Locate the active WSDL file via HTTP for the Web Service you want to call. The URL is provided in with the documentation that describes each Web Service: For Repository Web Services, see the ATG Repository Guide. For Personalization Web Services, see the ATG Personalization Programming Guide. For Commerce Web Services, see the ATG Commerce Programming Guide. Its important that you access the runtime and not the static version of the WSDL document. Assuming that you included the modules holding the Web Services you want to access when you assembled your application, you should be able to download the runtime version of the WSDL. 2. Use the Axis WSDL-to-Java tool to generate the client stub based on the WSDL. 3. Compile the client stub.
Creating and Compiling a Client

A Web Service client is a Java file that describes precisely what the Web Service should do. It provides the actions the Web Service should commit and initial values. If you want to enable Web Services to share sessions, your code needs to pass cookies between calls. The following example, which creates a static Web Service call to the loginUser Web Service, uses the CookieContainer class shown in Writing a CookieContainer Class (page 45):
{ LoginUserSEIService loginService = new LoginUserSEIServiceLocator(); LoginUserSEI loginStub = loginService.getLoginUserSEIPort(); org.apache.axis.client.Stub axisStub = (org.apache.axis.client.Stub) loginStub; CookieContainer cookieContainer = new CookieContainer(); axisStub.setMaintainSession(true); // Don't allow XML elements to reference other XML elements axisStub._setPropertyValue(AxisEngine.PROP_DOMULTIREFS, new Boolean(false)); // Push cookies onto the Stub cookieContainer.pushCookies(stub); String userId = loginStub.loginUser("bhavern", " xyo8bnif", false); // Get cookies out of the Stub, and pass them to subsequent calls as needed cookieContainer.extractCookies(stub); }
49
Creating a Call Using the Dynamic Invocation Interface (Dynamic)

A dynamic Web Service call holds all relevant information in one file, the client, which Axis converts directly into the SOAP message. Essentially, the client you create is a Java version of the call itself, excluding some relative values that are replaced with absolute ones at compile time. Keep in mind that if you want to access a Web Service that uses non-standard data types, you need to create your Web Service call following the static process. See Creating a Call Using a Client Stub (Static) (page 48). If you want to enable Web Services to share sessions, your code needs to pass cookies between calls. The following example, which creates a dynamic Web Service call to the loginUser Web Service, uses the CookieContainer class shown in Writing a CookieContainer Class (page 45):
Service service = new Service(); Call call = (Call) service.createCall(); // Get a hold of a CookieContainer passed to this method/class CookieContainer cookieContainer = new CookieContainer(); // Push previous cookies (if any) to the new Call object cookieContainer.pushCookies(call); call.setMaintainSession(true); call.setTargetEndpointAddress(new java.net.URL("http://hostname:port/userprofiling/usersession/loginUser/ loginUser") ); // Don't allow XML elements to reference other XML elements call.setProperty(AxisEngine.PROP_DOMULTIREFS,Boolean.FALSE) call.addParameter("Login", org.apache.axis.Constants.XSD_STRING, javax.xml.rpc.ParameterMode.IN); call.addParameter("Password", org.apache.axis.Constants.XSD_STRING, javax.xml.rpc.ParameterMode.IN); call.addParameter("IsPasswordEncrypted", org.apache.axis.Constants.XSD_BOOLEAN, javax.xml.rpc.ParameterMode.IN); call.setReturnType(org.apache.axis.Constants.XSD_STRING); call.setOperationName(new QName("http://www.atg.com/webservices", "loginUser")); String userId = (String) call.invoke( new Object[] { "bhavern", "xyo8bnif", Boolean.FALSE } ); // Extract new cookies from the Call into the CookieContainer object, // which can then be passed to subsequent calls cookieContainer.extractCookies(call); }
50
Creating a Serializer and Deserializer

When you want to use a Web Service that accesses RepositoryItems, you can create a mechanism for translating foreign content into different formats: A serializer will convert content from a native format into XML that will eventually undergo another conversion into a RepositoryItem. You need to create a serializer for set operations in which the client sends content to the Web Service in the context of the call. A deserializer constructs XML content that was originally formatted as RepositoryItems into a native content format. You need to create a deserializer for get operations in which a Web call returns content that represents a RepositoryItem. Both a serializer and a deserializer will need to understand the RepositoryItem schema. When you create the XML schema and a mapping file, youll need some information about the Web Service itself. You can find that information in the sections that describe the Web Service: For getProfile, see the ATG Personalization Programming Guide. For getOrderAsXML, getOrdersAsXML, getProductXMLById, getProductXMLByDescription, getProductXMLByRQL, getProductSkusXML, getPromotionAsXML, see the ATG Commerce Programming Guide. For Repository Web Services , see the ATG Repository Guide. Two Repository Web Services, getRepositoryItem and performRQLQuery, require a serializer and deserializer, but they can apply to any RepositoryItems you choose, which is different from the other Web Services that are only available to specific RepositorityItems and item descriptors. The serializers and deserializers you create require a Repository schema, which you can create by following these steps: 1. Create a Mapping file that determines which RepositoryItem properties will be captured by the Web Service and returned by the call. See Creating a Mapping File (page 51). 2. Use the generateXMLSchema tool to convert the RepositoryItem class into a standard XML schema. See Generating an XML Schema (page 52). 3. Insert a reference to the XML schema in your instance document, which is a document that represents an instance of the Web Service call. You complete this step when you configure the client stub; see Creating and Compiling a Client Stub (page 49) for instructions.
Creating a Mapping File

If you were to create an XML schema that included all RepositoryItem properties, some content may not be understood by standard deserializers and some may not conform to the XML 1.0 specification. Instead, you create a mapping file that determines which properties, from the RepositoryItem's item descriptor, to include or exclude from your XML schema. For instructions on how to create a mapping file, see Mapping Files (page 28). To create a mapping file, you need to know the properties defined by your item descriptor so you can decide which of them ought to be represented in the XML schema. You can find the location of a Repositorys item descriptor in the Oracle ATG Web Commerce platform Dynamo Administration UI: 1. In Dynamo Administration UI, click the Component Browser link.
51
2. Navigate to the Repository component that correlates to your Web Service as indicated in the documentation for your Oracle ATG Web Commerce Web Service. 3. Click the See Property Descriptions link beside the item descriptor name. For the item descriptor name, see the documentation for your Oracle ATG Web Commerce Web Service. This list that displays includes all properties that are available to the item descriptor based on the modules that are currently running. To make this XML schema compatible with the expectations of the resources that will use it, exclude the following items from your XML schema: 1. RepositoryItem properties that accept primitive data types and may be null. 2. RepositoryItem properties that accept Maps, Lists, or Sets.
Generating an XML Schema

The generateXMLSchema is a script that takes a given Repository component and item descriptor as arguments and produces an XML schema. For instructions on using this tools, see XML Schemas (page 32). When you create an XML schema in support of a Web Service, make sure that the same modules in the Oracle ATG Web Commerce platform are running now as those that will be running when the client calls the Web Service. For a list of Web Services, associated Repository components and items descriptors, see the documentation for your Oracle ATG Web Commerce Web Service. You may find these two optional arguments helpful: outputDirectory copies the resultant XML schema to the directory of your choosing. mappingFile specifies a file that describes the RepositoryItem properties to include in the resultant XML schema.
Other Required Schemas

When a client deserializes a RepositoryItem, it uses the schema derived from the item descriptor to reconstruct each repository object and its properties in the appropriate data types. Depending on the makeup of the item descriptor, you may need to also generate a schema for related item descriptors. Consider the Profile repository that uses the user item descriptor. There are two item descriptors, broker and investor, that are subtypes of user. If you were to use the updateProfile Web Service call while the Relationship Management platform is running, user and all subtypes of it that are part of Relationship Management are accessible. When you call updateProfile, its unclear which version of user you want to call: user, investor or broker. In this case, you need to generate XML schemes for all three item descriptors. In short, you need to generate an XML schema for all item descriptors used by RepositoryItems that are accessed by a Web Service call and for any related (parent or child) item descriptors that are running when the call is made. It is difficult to supply a general list of all item descriptors for which this added step applies because the contents of that list depend on many factors. When deciding if you need to create supplemental XML schemas for an item descriptor, consider the following: The Web Service you are calling
52
The modules running when you call that Web Service The contents of your Oracle ATG Web Commerce module stack The custom Oracle ATG Web Commerce components you have created that may extend existing components accessed by the Web Service Note: The previous discussion addresses item descriptors and their subtypes, meaning item descriptors that inherit from the parent class. This relationship should not be confused with that which item descriptors share with extensions of themselves, which are added by other modules. For example, the order item descriptor has one set of properties provided by the Consumer Commerce module. A second order item descriptor is supplied by Business Commerce and, when both modules are running, the order item descriptors are concatenated so that Business Commerce properties take precedence. Because all versions of order for the running module are combined into one, you need only one XML schema for the order item descriptor. When you create that XML schema for order, remember to do so while the same modules are running as will run when your Web Service calls that item descriptor.
53
54
Accessing ATG Web Services from .NET Clients
The Oracle ATG Web Commerce platform permits .NET clients to access Nucleus methods by exposing them as Oracle ATG Web Commerce Web Services. Many such Oracle ATG Web Commerce Web Services are included with the Oracle ATG Web Commerce platform as are tools for creating custom Web Services. For a list of Oracle ATG Web Commerce Web Services, see ATG Web Services (page 3). .NET clients are able to contact those Web Services through a carefully constructed call thats built in .NET, translated into XML wrapped in SOAP, transmitted to the Oracle ATG Web Commerce platform, and routed to the Nucleus method itself. Other Oracle ATG Web Commerce resources, such as JMS messages and RepositoryItems can also be exposed as Oracle ATG Web Commerce Web Services. This chapter aims to inform you how to call Oracle ATG Web Commerce Web Services from a .NET client. Rather than provide a broad discussion on how to use .NET, this chapter describes Oracle ATG Web Commercespecific features and processes that you need to be familiar with. Please see your .NET documentation for comprehensive instructions. To access an Oracle ATG Web Commerce Web Service, you need to be familiar with the following topics: About Web Services in the ATG Platform (page 55) Before You Begin Using a .NET Client (page 57) Calling ATG Web Services from a .NET Client (page 58) Using the Atg.DotNet.WebService API to Serialize and Deserialize RepositoryItems (page 60)
About Web Services in the ATG Platform

For the most part, you call ATG Web Services in the same way you call Web Services elsewhere. While the general process may not differ, its important that you are aware of these platform-specific features.
Security
The content you see as a response to a Web Service call depends on your access privileges. When you login using the loginUser Web Service, you provide your user identity. If session sharing is enabled, all subsequent Web Service calls in that session are associated with that identity and related role.
7 Accessing ATG Web Services from .NET Clients
55
For more information on loginUser, see the ATG Personalization Programming Guide. You may also want to learn how other Web Services handle the security information provided by loginUser. Such information exists in the ATG Repository Guide and the ATG Commerce Programming Guide.
Transactions
When a client calls a Web Service, the transactional behavior of the service is managed entirely on the server side. The method that is exposed as a Web Service can use standard transaction demarcation techniques, but the calling client has no control over this. There are some practical considerations you should be aware of. If a single Web Service call attempts to perform some operation, and the operation fails, the operation can be rolled back (provided that the Nucleus method is demarcated properly). However, a transaction cannot span multiple Web Service calls so if an operation is performed by a sequence of Web Service calls, and the final call fails, there is no way to roll back the steps performed by the previous calls.
Session Sharing
When you create a Web Service, you specify whether it should be executed within the context of an HTTP session. Associating Web Services with a session enables an application to maintain state across Web Service calls and to use login information for security purposes. To allow multiple Web Services to share a session on .NET, two things need to happen: 1. The Web Service client must allow a session to be shared across Web Service calls. To do this, you need to define the Web Service calls in the same Web Control and assign a CookieContainer for each call. For instructions, see Calling ATG Web Services from a .NET Client (page 58). 2. The Web Services themselves must support sessions. When you create custom Web Services, the Web Service Creation Wizard gives you the option of supporting sessions.
Client Stubs
The Oracle ATG Web Commerce platform provides preconfigured client stubs for all Oracle ATG Web Commerce Web Services in ATGWS.dll. To use these stubs you need to install ATGWS.dll. See Installing ATGWS.dll (page 57) for instructions. The client stubs provided here should be sufficient for your Oracle ATG Web Commerce Web Services. Note that simultaneous calls to a Web Service made by different threads will require that a unique client stub instance exist for each thread.
Web Services that Access RepositoryItems

Standard serializers and deserializers can handle some complex types, such as JMS messages sent to the ContentViewed and ContentRecommended Oracle ATG Web Commerce Web Services. When Web Services interact with proprietary technologies, such as RepositoryItems, standard serializers and deserializers dont understand the source data type so they arent able to recreate it. A RepositoryItem is a specialized JavaBean called a Dynamic Bean that produces basic get and set methods for the fields you define for it. Many complex items are stored by the Oracle ATG Web Commerce platform as RepositoryItems. The following Web Services transmit content thats natively stored as RepositoryItems: getProfile
56
getRepositoryItem performRQLQuery getOrderAsXML (Commerce users only) getOrdersAsXML (Commerce users only) getProductXMLById (Commerce users only) getProductXMLByDescription (Commerce users only) getProductXMLByRQL (Commerce users only) getProductSkusXML (Commerce users only) getPromotionsAsXML (Commerce users only) For these Web Services, you can use the Atg.DotNet.WebService API to serialize and deserialize related content. Descriptions for API classes are in Using the Atg.DotNet.WebService API to Serialize and Deserialize RepositoryItems (page 60). You can find this API in ATGWS.dll, which you need to install in order to access them. See Installing ATGWS.dll (page 57).
Before You Begin Using a .NET Client

Before you can access a Web Service, you need to make sure the Oracle ATG Web Commerce platform is ready for your call and .NET is configured: 1. Confirm that the application that includes the Web Service is deployed on your application server and is running. For more information, see Deploying Web Services (page 15). 2. Install Internet Information Service (IIS) and then Active Server Page.Net (ASP.NET) and VisualStudio.NET (VS.NET). 3. Install ATGWS.dll so you can access the stub and API classes it contains. See instructions below.
Installing ATGWS.dll
ATGWS.dll is a library that includes a stub class for each Oracle ATG Web Commerce Web Service. It also provides the Atg.DotNet.WebService API used for serializing and deserializing RepositoryItems. All users who want to access Oracle ATG Web Commerce Web Services from a .NET client should install ATGWS.dll.
You need two versions of ATGWS.dll on your system. One version lives in you Global Assembly Cache (GAC) so ASP.NET is able to access it when compiling the Web Service call. Another version should exist in a location that VS.NET recognizes. The instructions provided here direct you to use GACutil, a utility provided by .NET, although you can use any utility that can install ATGWS.dll to the Assembly folder in your windows directory. While the library does not need to live on the same machine as .NET, .NET needs to be able to access it. To install ATGWS.dll: 1. Copy <ATG10dir>/DAS/os_specific_files/i486-unknownwin32/ATGWS.dll to your Windows\Assembly folder.
57
2. Open a command prompt and enter the following command:

<DotNetdir>:\ gacutil/i <ATG10dir>/DAS/os_specific_files/i486-unknownwin32/ATGWS.dll
In this example, <DotNetdir> represents the parent directory, such as c:\DotNet that holds your .NET software. Keep in mind that each time you install a new version of ATGWS.dll, it coexists with older versions. The latest version of ATGWS.dll will instruct the .NET client to use it. Theres no need to uninstall ATGWS.dll when you want to install a new version. Remember when you do install new versions, you need to update references in VS.NET to the old version of ATGWS.dll. If youd like to remove all versions of ATGWS.dll, use this command in a command prompt:
<DotNetdir> gacutil/u <ATG10dir>/DAS/os_specific_files/i486-unknownwin32/ATGWS
Calling ATG Web Services from a .NET Client

This section describes the components you need in order to call an Oracle ATG Web Commerce Web Service. Because there are a few ways that you can generate a Web Service call on .NET, this section focuses only on the Oracle ATG Web Commerce resources you will use and assumes that you will refer to your .NET documentation for specific instructions. The following sections should provide guidance when creating a Web Service call: Accessing an ATG Web Service (page 58) Accessing a Custom ATG Web Service (page 58) Sample Web Service Calls (page 59)
Accessing an ATG Web Service

The Oracle ATG Web Commerce platform provides client stubs for all Oracle ATG Web Commerce platform Web Services in ATGWS.dll. Once you have installed a version of ATGWS.dll to your GAC and Assembly folders (see Installing ATGWS.dll (page 57) for instructions), you need to do two things: 1. In your Visual Studio .NET project, make a reference to ATGWS.dll. 2. Create instances of the client stubs and use them in your Web Service call.
Accessing a Custom ATG Web Service

To access a Web Service that you created in the Oracle ATG Web Commerce platform, you create client stub and a reference to it in your Visual Studio.NET project: 1. Assemble your application. Make sure you include the modules that contain the Web Services you want to access.
58
2. Deploy the application on your application server and start it up. 3. In your Visual Studio .NET project, add the Web Services as Web References. 4. When prompted for an Address, provide the WSDL URI, such as:
http://hostname:port/repository/generic/getItem?WSDL
You can find the URI for Oracle ATG Web Commerce Web Services in the documentation for the specific Web Service: For Repository Web Services, see the ATG Repository Guide. For Personalization Web Services, see the ATG Personalization Programming Guide. For Commerce Web Services, see the ATG Commerce Programming Guide.
Sample Web Service Calls

The Web Service call is a document that incorporates calls to any number of Oracle ATG Web Commerce Web Services that may exist in the same session. For each Web Service, you create an instance of the client stub, call methods on the Web Service, and call the Web Service itself. These Web Service calls are written in C#.
A Simple Call
This Web Service call obtains a RepositoryItem by accessing the getRepositoryItem Oracle ATG Web Commerce Web Service.
using Atg.DotNet.WebService.Repository.GetRepositoryItem; // ... // create stub instance GetRepositoryItemSEIService getItemClientStub = new GetRepositoryItemSEIService(); // assign URL of web service getRepositoryItemClientStub.Url = "http://example.com/repository/generic/getItem/getRepositoryItem"; // call web service string itemXml = getRepositoryItemClientStub.getRepositoryItem("/nucleus/path/to/repository", "itemDescriptorName", "repositoryId");
A Complex Call
The following code demonstrates how you would construct a call that uses security controls to restrict the information users can access. Notice that the loginUser Web Service establishes the user identity role, which other Web Services refer to. Because an instance of a CookieContainer is created in this code and assigned to each Web Service stub, all Web Services called here exist in the same session. For brevity these examples omit some details such as a exception handling for the SoapException as well as class syntax.
using System.Net; // for CookieContainer using Atg.DotNet.WebService.Repository.GetItem;
59
using Atg.DotNet.WebService.Repository.PerformRQLQuery; using Atg.DotNet.WebService.UserSession.LoginUser; using Atg.DotNet.WebService.UserSession.LogoutUser; // create stub instances GetItemSEIService getItemClientStub = new GetItemSEIService(); PerformRQLQuerySEIService performRQLQueryClientStub = new PerformRQLQuerySEIService(); LoginUserSEIService loginUserClientStub = new LoginUserSEIService(); LogoutUserSEIService logoutUserClientStub = new LogoutUserSEIService(); // create a new cookie container for our session and share it between // the various stub instances CookieContainer cookieContainer = new CookieContainer(); getItemClientStub.CookieContainer = cookieContainer; performRQLQueryClientStub.CookieContainer = cookieContainer; loginUserClientStub.CookieContainer = cookieContainer; logoutUserClientStub.CookieContainer = cookieContainer; // authenticate the user for the session loginUserClientStub.loginUser("user", "password", false); // call services string itemXml = getItemClientStub.getItem("/nucleus/path/to/repository", "itemDescriptorName", "repositoryId"); string[] itemsXml = performRQLQueryClientStub.performRQLQuery("/nucleus/path/to/repository", "itemDescriptorName", "property = 'value'"); // log out the user logoutUserClientStub.logoutUser();
Using the Atg.DotNet.WebService API to Serialize and Deserialize RepositoryItems

The Atg.DotNet.WebService API is a mechanism that you can use to serialize and deserialize RepositoryItem content. The primary role of this API is to: Converts a RepositoryItem into an XML document (serialization). Formats an XML document into a RespositoryItem (deserialization). By understanding the Oracle ATG Web Commerce RepositoryItem API, Atg.DotNetWebService.RepositoryItem is able to convert into objects any content that uses the RepositoryItem API for its underlying data type. You can use this API for Oracle ATG Web Commerce and custom Web Services that access RepositoryItems. The Atg.DotNet.WebService is made up of the following classes: RepositoryItem Class (page 62) Property Class (page 63)
60
RepositoryItemRef Class (page 63) Complex Type Class (page 64) NoSuchPropertyException Class (page 64) RepositoryItemSerializer Class (page 65) RepositoryItemSerializationException Class (page 65) Note: Rather than use this API, you could generate an XML schema representation of the RepositoryItem and use that serialize/deserialize content. The advantage of using an XML schema is that you can control the properties you use, meaning you can easily exclude certain properties from your schema. You may find the disadvantages, namely the limitations in property types and values that this method supports, reason to use the provided API instead. For instructions on how to use an XML schema for serialization/deserialization, see the Creating a Serializer and Deserializer (page 51) in the Java client chapter.
About the Atg.DotNet.WebService API

Collectively, these classes provide you with the ability to serialize and deserialize RepositoryItems and to configure both processes. Although this discussion specifically describes the serialization process, the same principles apply to both processes. When you want to deserialize content from a Web Service, for example, you use the response sent by Oracle ATG Web Commerce Web Service resulting from your initial Web Service call. The response, formatted in XML, holds a string object that represents Oracle ATG Web Commerce RepositoryItems. Once you make the call to the API to deserialize the string, the deserializer parses the string into a RepositoryItem object. Not all content in the string is emitted by the serializer. By default, only content specified as dirty, meaning a different value for it exists in the Oracle ATG Web Commerce platform and the external system .NET communicates with, is serialized. Once an item has been serialized, theres parity across systems so all properties on that item are marked as clean. You can alter the default dirty/clean designation in the following ways: Use the RepositoryItem.Dirty property to toggle an objects clean/dirty status. Use the RepositoryItem.setPropertyDirty() methods to toggle a propertys clean/dirty status. During deserialization, content that represents RepositoryItem properties is parsed based on a few rules. All properties are converted back to the native data type, assuming that data type is available in .NET. The following data types dont exist in .NET and so values for these types are converted as follows: Oracle ATG Web Commerce Map properties use Hashtable data type in .NET. Oracle ATG Web Commerce Date or Timestamp properties are stored as .NET DateTime data type. Oracle ATG Web Commerce Set properties are formatted as .NET Array data type. Oracle ATG Web Commerce properties that refer to other Oracle ATG Web Commerce RepositoryItems behave as .NET Hashtables. For the most part, Atg.DotNet.WebService determines format output type by relying on prior processing. For example, if it had deserialized a particular RepositoryItem, such a Growth fund, then assuming no new properties are added, when the Growth fund is serialized, Atg.DotNet.WebService.RepositoryItem is aware of each propertys destination data type. However, in all other circumstances, you should explicitly include the XML data type for the property. In short, under these circumstances include data types: The first time a RepositoryItem is serialized when it hasnt been previously deserialized, such as in the case of adding a new item to the Oracle ATG Web Commerce platform.
61
A new property value is assigned to an empty RepositoryItem. Note: In order to use the classes in this interface, make sure that the Oracle ATG Web Commerce platform atg/ repository/xml/RepositoryXMLTools component has the encodeRepositoryIdAsAttr property set to true. This is the default setting.
RepositoryItem Class
The Atg.DotNet.WebService.RepositoryItem class is designed to manage XML serialization and deserialization for easy interoperability with the .NET Web Services framework. To serialize or deserialize a RepositoryItem, you need only to pass in the RepositoryName and RepositoryId. When you are working with content for the first time, you also need to call setPropertyType to instruct the deserializer/serializer to use a specific output data type.
Properties
Dirty Determines the overall dirtiness of an object by specifying whether all properties are clean (false) or one of more properties are dirty (true). ItemDescriptorName Name of the item descriptor associated with the objects RepositoryItem. Properties List of properties for this RepositoryItem. RepositoryId ID provided to the objects RepositoryItem representation. RepositoryName Name of the repository that the RepositoryItem is part of.
Constructors
RepositoryItem() Constructs a new, empty RepositoryItem object. When you serialize or deserialize a property with a value that is a pointer to a RepositoryItem, be sure to supply it a RepositoryName, RepositoryId, and ItemDescriptorName when you invoke the setRepositoryItem method. RepositoryItem(string) Constructs a new RepositoryItem in the Oracle ATG Web Commerce platform, populating it with values parsed from the XML instance of the Web Service call. The XML instance is a by-product from the Web Service call generation.
Methods
clearPropertyValues Clears all property values for a given RepositoryItem. Before using RepositoryItemSerializer.deserialize, its a good idea to use this method to clear all previous values. isPropertyDirty Determines whether a given property value is dirty (true) or clean (false). setPropertyDirty Designates a given property as dirty.
62
getPropertyValue Returns the value provided for a property in the Oracle ATG Web Commerce platform. If the property does not exist in the Oracle ATG Web Commerce platform, an error of type ATGWS.NoSuchPropertyException is thrown. setPropertyValue Sets a value for a property in the Oracle ATG Web Commerce platform. getPropertyType Returns the propertys XML data type. setPropertyType Specifies the XML data type for the property value. serialize Creates a string representation of an XML document for the RepositoryItem.
Property Class
This class represents a given propertys name and value.
Properties
Dirty Determines whether a given property is dirty (true) or clean (false). If you indicate that a property value should change by invoking the RepsoitoryItem setPropertyValue call, this property is set to true. Once a response is returned from the setPropertyValue call, this property is set to false. XmlType XML data type that will be used to represent the propertys value.
Constructor
Property() Constructs an empty object representing a property.
Methods
getName Returns the name of the property. getValue Returns the value of the property. setValue Sets a new value to the property.
RepositoryItemRef Class
This class represents a reference to another RepositoryItem.
Properties
RepositoryName
63
Name of the repository of which the referenced RepositoryItem is a part. ItemDescriptorName Name of the item descriptor used by the referenced RepositoryItem . RepositoryId ID for the referenced RepositoryItem .
Method
setRepositoryItem Initializes the ItemRef to refer to the provided RepositoryItem.
Complex Type Class

This class permits you to serialize/deserialize properties that use complex types by specifying an output data type explicitly.
Properties
TypeName Data type for the RepositoryItem property. Properties Name of any properties that are either deserialized from or serialized into the complex type.
Constructor
ComplexType() Constructs an empty object to represent all properties of a complex data type.
Methods
getPropertyValue Retrieves values from the Oracle ATG Web Commerce platform for the specified properties. If the property does not exist in the Oracle ATG Web Commerce platform, an error of type ATGWS.NoSuchPropertyException is thrown. setPropertyValue Sets a property to a value supplied as an input. getPropertyType Returns the XML data type for the property value. setPropertyType Specifies the XML data type for the property value.
NoSuchPropertyException Class
This class generates an exception each time a getProperty or getPropertyValue method tries to interact with a property that has not been specified for the designated RepositoryItem.
Properties
PropertyName
64
Name of the property that you are trying to work with.
Constructor
NoSuchPropertyException Constructs the exception.
RepositoryItemSerializer Class
This class conducts serialization/deserialization and permits you to decide if you want all or only dirty properties to be updated. Constructors RepositoryItemSerializer() Constructs a serializer instance. RepositoryItemSerializer(RepositoryItem) Constructs an object holding serialized content.
Methods
deserialize (string) Deserializes an XML-formatted string into a new RepositoryItem. deserialize (string, boolean) Deserializes an XML document string into a RepositoryItem. Additional arguments true or false indicate whether values for only dirty properties (true) or all properties (false) should be deserialized. serialize (string) Serializes a RepositoryItem into an XML-formatted string document. serialize (boolean) Serializes a RepositoryIteminto an XML document. Additional arguments true and false indicate whether values for only dirty properties (true) or all properties (false) should be deserialized.
RepositoryItemSerializationException Class
This class creates an exception object when errors occur during serialization or deserialization. Constructor RepositoryItemSerializationException() Constructs an empty exception object.
65
66
Part II. Integration Framework

In addition to the Oracle ATG Web Commerce Web Services functionality discussed in the preceding chapters, the Oracle ATG Web Commerce platform includes a more generalized framework that enables you to integrate your applications with remote software systems for cases where using Web Services might not be appropriate. For example, you could use the integration framework to integrate an ATG Commerce application with an order-processing system. When a customer places an order through ATG Commerce, the order data can be transferred to the order-processing system, and the Oracle ATG Web Commerce platform can trigger events that invoke the processing facilities in the remote system. The integration framework involves several key facilities that you can use to integrate Oracle ATG Web Commerce applications with remote systems: JMS messaging, configured through Patch Bay, to enable the Oracle ATG Web Commerce platform to trigger events in the remote system, or the remote system to trigger events in the Oracle ATG Web Commerce platform. See the Dynamo Message System chapter of the ATG Platform Programming Guide. Remote Procedure Calls (page 95) (RPC), for inter-application command execution. For example, the Oracle ATG Web Commerce platform can use RPC to query an inventory management system. Data integration, using the Repository to XML Data Binding (page 27) facility (described in Part I of this guide) and the IntegrationRepository (page 74). You can use these facilities individually, but a typical integration will use all of these facilities together. For example, the Integration Repository typically uses RPC to execute the commands used to move data between the Oracle ATG Web Commerce platform and the remote system.
Integrators and Adapters

Integrating the Oracle ATG Web Commerce platform with a remote system generally involves additional software to handle the communication between the two systems: A middleware transport layer, such as Tibco or MQ Adapters that enable the Oracle ATG Web Commerce platform and the remote system to communicate through the middleware transport layer An integrator that implements the Integration Frameworks queries and commands in a form understood by the remote system, enabling the two systems to interoperate and share data The following figure illustrates the Oracle ATG Web Commerce integration architecture:
You can write adapters and integrators by implementing the various APIs described in this manual. Note that Oracle ATG Web Commerce adapters handle only the communication between the Oracle ATG Web Commerce platform and the middleware transport. Adapters for communication between a remote system and a middleware transport are typically available from the company that develops the remote system or the middleware.
Using the Integration Repository
The Oracle ATG Web Commerce Integration Framework includes the Integration Repository, which adds to the Oracle ATG Web Commerce Repository feature the ability to represent data on external systems as Oracle ATG Web Commerce repository items. The Integration Repository provides several key features for integrating Oracle ATG Web Commerce with external systems: You can execute queries from Oracle ATG Web Commerce against remote systems. The Integration Repository represents the results of the queries as repository items. You can create queries using RQL or other Oracle ATG Web Commerce query building techniques, and the Integration Repository translates the queries into the format required by the remote system. When data from the remote system is represented as repository items, the Integration Repository can automatically submit changes to these items to the remote system without requiring special update calls to a remote system.
Architecture
The Integration Repository is a wrapper around an Oracle ATG Web Commerce SQL repository, which is referred to as the local repository. In a system architecture that uses an Integration Repository, the integrated data resides in the remote system, rather than just in a local database, and queries are made using the RPC command structure described in the Remote Procedure Calls (page 95) chapter. Just like other repositories, an Integration Repository defines one or more item descriptors. Each item descriptor defines one or more commands to be used for the operations that need to interact with the remote system: executeQuery getItem createItem updateItem removeItem These operations are described in more detail in the Command Operations (page 79) section of this chapter. Each command involves an RPC call that may access the remote system, as described in the Remote Procedure Calls (page 95) chapter. The Integration Repository enables you to use the Oracle ATG Web Commerce Repository Query Language (RQL) and all the RQL droplets to access data that is stored on remote systems. The translation between RQL and the query format required by the remote system is handled by an implementation of the
8 Using the Integration Repository
69
IntegrationRepositoryView (page 78) class. An implementation of IntegrationRepositoryView typically needs to be written for each remote system you want to integrate with Oracle ATG Web Commerce. Wrapping the SQL repository provides the Integration Repository with superior performance and robustness by leveraging the SQL repositorys sophisticated item caching features. You can persist data from the remote system locally in a SQL repository. By maintaining locally-cached copies of the remote data, the Integration Repository can make the data available more quickly than if you needed to access the remote system every time you needed to access the data. In addition, the local SQL repository offers a degree of protection against the remote system being temporarily unavailable. More details of the Integration Repository architecture are described in the Integration Repository APIs (page 73) section of this chapter.
Integration Approaches
The Integration Repository is designed to help integrate Oracle ATG Web Commerce applications with remote systems. It assumes that your business maintains data on a remote system and you want to expose and possibly modify this data within your Oracle ATG Web Commerce application in the form of Oracle ATG Web Commerce repository items. There are several ways you can set up such an integration, depending on the demands of your Oracle ATG Web Commerce application and the characteristics of the remote system and the data maintained there. Here are four possible approaches for getting remote data. Which approach to choose depends on balancing your need for consistent data and best performance.
Remote Only
In this case, the data is maintained only on the remote system. Each time that the Oracle ATG Web Commerce application needs to access the data, a command is issued to the remote system. The local repository is configured to use transient repository items. Advantages: You are always sure that the data returned to Oracle ATG Web Commerce is up to date. Disadvantages: If the remote system is unavailable, then no form of the data is available to the Oracle ATG Web Commerce application. Frequent queries to the remote system can affect the performance of the remote system, which may also be serving functions other than the Oracle ATG Web Commerce application. The need to query the remote system will tend to slow the performance of the Oracle ATG Web Commerce application. See Configuring the Remote-Only Model (page 84) for more details about how this approach could be configured.
Remote then Local

In this case, the primary source for the data is the remote system. Each time that the Oracle ATG Web Commerce application needs to access the data, a command is issued to the remote system. If the command fails to return, then the command is issued to the local repository.
70
Advantages: You are sure that the data returned to Oracle ATG Web Commerce is up to date, except in cases where the remote system is unavailable. In addition, the existence of the local repository can provide a backup form of the data, in case the remote system is inaccessible. Disadvantages: Frequent queries to the remote system can affect the performance of the remote system, which may also be serving functions other than the Oracle ATG Web Commerce application. The need to query the remote system will tend to slow the performance of the Oracle ATG Web Commerce application. See Configuring the Remote-then-Local Model (page 85) for more details about how this approach could be configured.
Local then Remote

In this case, a version of the data is maintained in a local repository. Only if the data is not available locally, or if the local copy has been marked invalid or has expired, does the Integration Repository query the remote system for the data. You might use this integration model if you need to make sure the system is as fast as possible, and you dont have to worry so much about data consistency because the data does not change that often. When the remote system is down, you can block changes to the data (updates, creating and removing items), but you make the data available from the local system, so that your users can continue to work. Advantages: Oracle ATG Web Commerces performance is as fast as possible. There are fewer queries to the remote system, so less burden is placed on the remote system. You can configure the lifetime of items in the local repository, so you can be assured that the data is not out of date by more than a specified amount of time. Disadvantages: You have less assurance that the data returned from the local repository is consistent with the data in the remote system. See Configuring the Local-then-Remote Model (page 86) for more details about how this approach could be configured.
Local Only
This approach doesnt need to use the Oracle ATG Web Commerce Integration Framework. In this case, we periodically dump data from the remote system into the relational database used by the Oracle ATG Web Commerce application. The data is accessed by the SQL repository. Since this approach doesnt need to issue commands against the remote system in real time, there doesnt need to be an Integration Repository. Advantages: Oracle ATG Web Commerces performance is as fast as possible. The only interaction with the remote system is a periodic batch data transfer, which probably can be scheduled to place a minimal burden on the remote system.
71
Disadvantages: The local repository is not updated in real time, so any changes in the remote system are reflected in the local repository and therefore in your Web application only after the scheduled data transfer.
Setting Up an Integration Repository

Here is a brief overview of the steps involved in setting up an Integration Repository: 1. Create and configure an Integration Repository. This is a component of class atg.adapter.integrations.IntegrationRepository. Configure the properties described in the IntegrationRepository (page 74) section. 2. Create the Integration Repositorys definition file, as described in the Defining an Integration Repository (page 72) section. 3. Create and configure your local repository. The local repository is a normal SQL repository. See SQL Repository Overview in the ATG Repository Guide for more information. 4. Create the database schema for your local repository. 5. Create any mapping files you desire for each item descriptor in the Integration Repository. See Mapping (page 82) for more information. 6. Create a subclass of IntegrationRepositoryView for each remote system you need to query. 7. Create Commands that correspond to each of the command operations you want to define for your Integration Repository. See the Remote Procedure Calls (page 95) chapter. To set up a complete integration with a remote system, you will also need to perform many tasks that are outside the scope of this chapter. You will need to configure the transport layer that connects Oracle ATG Web Commerce to the remote system. You will also typically want to create a portlet (Oracle ATG Web Commerce Portal gear) or set of form pages to display and modify data from the remote system.
Defining an Integration Repository

The Integration Repository is defined by an XML template file. This file is specified by the definitionFile property of the IntegrationRepository component. The Integration Repository definition file defines the integration behavior, including the commands used for the executeQuery, getItem, createItem, updateItem, and removeItem integration operations. The elements of the Integration Repository definition file are described in the Integration Repository Definition File (page 87) section. The commands are described in the Command Operations (page 79) section. Since the Integration Repository wraps another repository, the underlying SQL repository also requires a definition file to define the repository item properties. You may also want to create mapping files to handle the relation of your repository item properties to the data maintained on the remote system. See the Repository to XML Data Binding (page 27) chapter for more information. This is an example of what the Integration Repository definition file would look like. It defines a single item descriptor, named account, and specifies the Commands used to query, get, add, update, and remove account items:
72
<integration-repository-template> <header> <name>RemoteX Repository</name> </header> <item-descriptor name="account"> <query command="/atg/integrations/remotex/queries/AccountQuery" view="atg.integrations.remotex.RemoteXView"> </query> <get-item command="/atg/integrations/remotex/queries/AccountQuery"> </get-item> <add-item command="/atg/integrations/remotex/queries/AccountUpdateRPC"> </add-item> <update-item command="/atg/integrations/remotex/queries/AccountUpdateRPC"> </update-item> <remove-item command="/atg/integrations/remotex/queries/AccountDeleteRPC"> </remove-item> </item-descriptor> </integration-repository-template>
The Integration Repository definition file conforms to a DTD file at this URL:
http://www.atg.com/dtds/integrations/integration-repository_1.0.dtd
The Integration Repository is also configured using normal JavaBean properties. An IntegrationRepository component might be configured in a properties file like this:
$class=atg.adapter.integrations.IntegrationRepository repositoryName=MyStuff localRepository=/mystuff/MyLocalRepository definitionFile=/mystuff/irConfig.xml transactionManager=/atg/dynamo/transaction/TransactionManager integrationRepositoryTools=/atg/integrations/repository/IntegrationRepositoryTools persistentCacheManager=/atg/integrations/repository/PersistentCacheManager mappingManager=/atg/repository/xml/SchemaManager mappingTools=/atg/integrations/repository/MappingTools lockManager=/atg/dynamo/service/ClientLockManager
The IntegrationRepository (page 74) section describes these properties.
Integration Repository APIs

The Integration Repository consists of a set of item descriptors. Each item is queryable through a RepositoryView using a QueryBuilder. Each item descriptor is associated with a particular Command or set of Commands. One of these Commands returns results that are converted to repository items of the given item descriptor. Other Commands are used for updating or deleting values in the remote system.
73
The Integration Repository includes extensions to, or implementations of, the following repository classes. Each of these classes is in the atg.adapter.integrations package.
IntegrationRepository (page 74) extends atg.repository.RepositoryImpl
IntegrationRepositoryItemDescriptor (page 76) extends atg.repository.ItemDescriptorImpl
IntegrationRepositoryItem (page 77) implements atg.repository.RepositoryItem, atg.repository.MutableRepositoryItem
ChangedPropertyBean (page 77) implements atg.repository.RepositoryItem, atg.repository.MutableRepositoryItem
atg.repository.databinding.MappingRepositoryItem (page 77) implements atg.repository.RepositoryItem, atg.repository.MutableRepositoryItem
IntegrationRepositoryView (page 78) extends atg.repository.RepositoryViewImpl
In addition, each IntegrationRepositoryItemDescriptor refers to one or more commands, which implement the atg.integrations.Command interface. The RPC call in a Command returns an object of the atg.integrations.CommandResult class. Command and CommandResult are discussed in the Remote Procedure Calls (page 95) chapter.
IntegrationRepository
extends RepositoryImpl The IntegrationRepository references another repository, which is referred to as the local repository and which is a SQL repository. The IntegrationRepository is defined by a Nucleus properties file and an XML definition file. Each method call functions as described in the Methods (page 62) section, forwarding the request either to the local repository or to the IntegrationRepositoryItemDescriptor, which then executes a Command against the remote system.
Properties
localRepository The SQL repository that acts as a local repository. The local repository is a normal SQL repository. It might be configured in a properties file like this:
//mystuff/MyLocalRepository.properties $class=atg.adapter.gsa.GSARepository definitionFiles=/mystuff/localConfig.xml repositoryName=MyLocalStuff groupContainerPath=/atg/registry/RepositoryGroups
74
XMLToolsFactory=/atg/dynamo/service/xml/XMLToolsFactory transactionManager=/atg/dynamo/transaction/TransactionManager dataSource=/atg/dynamo/service/jdbc/JTDataSource idGenerator=/atg/dynamo/service/IdGenerator
definitionFile The Integration Repository definition file. This is an XML file that uses the Integration Repository DTD, http:// www.atg.com/dtds/integrations/integration-repository_1.0.dtd . See Integration Repository Definition File (page 87) for information about creating an Integration Repository definition file integrationRepositoryTools This is a property of type atg.adapter.integrations.IntegrationRepositoryTools. This class provides a set of helper methods that are used to convert between the local repository items and the remote systems data format. An instance of this class exists at /atg/integrations/repository/ IntegrationRepositoryTools. persistentCacheManager This is a property of type atg.adapter.integrations.PersistentCacheManager. This class provides management of persistent caching. An instance of this class exists at /atg/integrations/repository/ PersistentCacheManager. See the Persistent Caching (page 82) section. mappingManager This is a property of type atg.repository.databinding.MappingManager. You can optionally define a mapping of the local repository item to the data on the remote system. This class manages that mapping. See Mapping (page 82) in this chapter and see also the Repository to XML Data Binding (page 27) chapter. mappingTools This is a property of type atg.repository.databinding.MappingTools, which is a helper class to manage the mappings. An instance of this class exists at /atg/integrations/repository/MappingTools. defaultTimeoutResponse The Integration Repository needs to deal with the case of a Command timing out before a result is returned from the remote system. If the Command times out, this property defines what the default behavior should be. There are four choices:
ROLLBACK INVALID UNKNOWN IGNORE
Rollback the current transaction. Mark the items state as invalid. See Persistent Caching (page 82). Mark the items state as unknown. See Persistent Caching (page 82). Do nothing.
sendScenarioEvents A boolean property that controls whether the repository sends scenario events. The Integration Framework includes one scenario event by default, atg.adapter.integrations.IntegrationExternalIdChange, which is sent when the externalId of an item is set. To trigger this event, use the IntegrationRepositoryTools.externalIDWasUpdated method.
Methods
Most methods in the IntegrationRepository class are pass-through to the local repository. The following methods provide special behavior:
75
getItem Depending on how you have configured the Integration Repository, this method either: calls localRepository.getItem and, if the result is null, then calls IntegrationRepositoryItemDescriptor.getRemoteItem, or calls IntegrationRepositoryItemDescriptor.getRemoteItem and, if the result is null, then calls localRepository.getItem, or calls IntegrationRepositoryItemDescriptor.getRemoteItem only. Both the local repositorys query cache and the IntegrationRepositorys query cache will be used depending on the item descriptor. If the IntegrationRepository definition file includes a query Command, then the IntegrationRepository executes the query (and uses its query cache). If there is no query Command, then the query is forwarded to the local repository. For a more detailed description, see getItem (page 80) in the Command Operations (page 79) section. getView This method can operate in two ways. If querying is implemented in the local repository (no query command) then this returns a LocalRepositoryViewWrapper. If a Command is used for querying then this returns the configured RepositoryView class. getItemDescriptor Return an IntegrationRepositoryItemDescriptor (page 76) that wraps an item descriptor from the local repository. The local repositorys item cache will be used. getItemForUpdate getItemsForUpdate Return one (or more) IntegrationRepositoryItem, using similar behavior to the getItem method above. createItem Call localRepository.createItem. This method is just a pass through. See addItem. addItem Call localRepository.addItem. Also call IntegrationRepositoryItemDescriptor.addRemoteItem. For a more detailed description, see addItem in the Command Operations (page 79) section. updateItem Call localRepository.updateItem. Also call
IntegrationRepositoryItemDescriptor.updateRemoteItem. For a more detailed description, see
updateItem in the Command Operations (page 79) section. removeItem Call localRepository.removeItem. Also call
IntegrationRepositoryItemDescriptor.removeRemoteItem. For a more detailed description, see
removeItem in the Command Operations (page 79) section. Each of the Command executions is relevant only if the given command is defined for the item descriptor.
IntegrationRepositoryItemDescriptor
extends ItemDescriptorImpl This class references an item descriptor from the local repository. Most operations will be pass-through to the local repository item descriptor. The following operations (described in the Command Operations (page 79) section) execute a Command if one is defined for the item descriptor; otherwise they do nothing.
76
executeQuery getItem updateItem addItem removeItem
In addition, this class is responsible for converting the results of queries obtained from the remote system into repository items.
IntegrationRepositoryItem
implements RepositoryItem, MutableRepositoryItem This class references a repository item in the local repository. Most operations will be passed through to it.
ChangedPropertyBean
implements RepositoryItem, MutableRepositoryItem This class includes only the external ID property plus the list of properties in a RepositoryItem that have been changed. When, for example, updateItem is invoked on an IntegrationRepositoryItem, this wrapper can be passed to the update Command instead of the RepositoryItem. This allows us to send only the changed properties to be saved to the remote system, instead of trying to update all the properties of a repository item. For example, if you change the middleName property of the user profile, and the user profile is configured with an external id property called remoteId, the ChangedPropertyBean will only expose two properties: middleName and remoteId. If you call ChangedPropertyBean.getPropertyDescriptors, the result will only contain these two properties. A ChangedPropertyBean is read-only.
atg.repository.databinding.MappingRepositoryItem
implements RepositoryItem, MutableRepositoryItem A MappingRepositoryItem wraps a repository item and exposes properties as they are configured in a mapping file. The Integration Repository creates MappingRepositoryItems automatically if it is configured with a mapping file. The property names that are exposed are the target names as defined in the mapping file. If a propertys include attribute is false in the mapping file, then that property is not a legal property of the MappingRepositoryItem. For example, if the following mapping exists:
<item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="user" default-include="false"> <property name="firstName" include="true"/> <property name="lastName" include="true"/> <property name="id" target-name="dynamoId" include="true"/> </item-descriptor>
then the corresponding MappingRepositoryItem would contain three properties: firstName, lastName, and dynamoId. See the Repository to XML Data Binding (page 27) chapter.
77
IntegrationRepositoryView
extends RepositoryViewImpl
IntegrationRepositoryView is an abstract class that provides some standard operations like applyOptions and getRange. For each type of remote system that you want to integrate with, you need to create an implementation of IntegrationRepositoryView specific for your remote system in order to provide the translation between the Oracle ATG Web Commerce Query format, and the format expected by the remote system. When a query is executed, the executeUncachedQuery method is called. That method looks like this:
public RepositoryItem[] executeUncachedQuery(Query pQuery, QueryOptions pOptions) { // Step 1 Object input = createQueryCommandInput(pQuery, pOptions); // Step 2 RepositoryItem[] items = executeQueryCommand(input); // Step 3 return applyOptions(items, pOptions); }
The inputs to this method are a standard Query object and a standard QueryOptions object. The executeUncachedQuery method goes through the following steps: Step 1 The first thing the view needs to do is translate the Query object into an object that is understandable by the remote system. This is the responsibility of your subclass of IntegrationRepositoryView and the only method that you must implement. Step 2 This step is a call to the method defined in IntegrationRepositoryView that gets the correct Command according to your configuration and calls Command.execute with the provided query input. Step 3 This step may not be necessary. If your remote system supports sorting and ranging (returning a subset of the items) then it will be more efficient for that information to be included in the command input. In that case this step can be skipped in the executeUncachedQuery and you should override the applyOptions method to do nothing. The only thing required for querying to work is to subclass IntegrationRepositoryView and implement createQueryCommandInput. The implementation of this method will introspect the Query class and create an input object. The type and contents of the input object depend on the requirements of your application and the remote system you are querying. You then need to create a Command that knows what to do with this input. In addition, you will typically need to implement a processResults method in your IntegrationRepositoryView subclass. This method is responsible for translating between the remote data format and the repository items in the local repository. The default implementation of IntegrationRepositoryView.processResults calls IntegrationRepositoryTools.createRepositoryItems. It passes in the results from pCommandResult.getResults() as the first argument. The createRepositoryItems method uses DynamicBeans to look at the given command results. For each object in the result it uses the IntegrationRepositoryItemDescriptor to find the external ID. It uses this external ID to look for an existing item in the local repository with the same external ID. If one is found, this method iterates across the
78
properties in the result object (using DynamicBeans) and updates the properties. If one is not found, a new item is first created, then the properties are updated.
Command Operations
The Integration Repository can define five types of operations that allow Oracle ATG Web Commerce repository items to access data in remote systems: executeQuery (page 79) getItem (page 80) addItem (page 25) updateItem (page 25) removeItem (page 25)
executeQuery
There are four possibilities here: Always query against the local repository. For example, you may decide that updates to profiles need to be sent to a remote system, but queries of that data will always be done locally. Always query against the remote system. For example, you may want the data to remain in the remote system with no persistent storage in Dynamo. Check the local repository first, then check the remote system. Check the remote system first, then Dynamo. If there is a Command associated with the query operation then the remote system is queried. If no Command is configured, then the local repository is queried. When you want to execute a query against the Integration Repository, your code will look something like this:
Repository rep = getRepository(getMyRepository()); RepositoryView view = rep.getView(getMyView()); QueryBuilder builder = view.getQueryBuilder(); Query query = builder.createSomeQuery(MyQueryExpression); RepositoryItem[] results = view.executeQuery(query);
There is no Integration Repository specific code in any of this. This is because you build queries with the Integration Repository in exactly the same way that you would build queries with the SQL repository. This also means that you can use RQL. You can use standard query builder calls, so the Query object that gets generated is a standard Query object from the atg.repository.query package. This real difference is in the RepositoryView. The Integration Framework uses a subclass named IntegrationRepositoryView. This class provides an implementation of executeUncachedQuery that is expected to call the query Command. There needs to be a subclass of IntegrationRepositoryView for each remote system you want to query. This subclass is responsible for translating between the Oracle ATG Web Commerce Query and the query format expected by the remote system.
79
A query Command will receive whatever input is created by the createQueryCommandInput method of your IntegrationRepositoryView. The IntegrationRepositoryView.processResults method is responsible for translating between the remote data format and our repository items.
getItem
The getItem operation returns the value from the local repository. If there is no result, or if the entry in the local repository is invalid, the getItem operation updates the local repository with the results returned by the execution on the remote system of the Command associated with the getItem operation. This operation uses the IntegrationRepositoryItemDescriptor.getRemoteItem() method. Commands executed for get-item will receive whatever input is created by IntegrationRepositoryTools.createGetCommandInput(). By default this is a map of the external ID property name to the value of the external ID. If you require a more complex command input, extend IntegrationRepositoryTools and override the createGetCommandInput() method. If the item descriptors use-external-id attribute is true, then the given local repository item ID is identical to the remote ID. If this attribute is false, then the remote ID must be retrieved from the local item (using the item descriptors external-id-property). If getRemoteItem throws an exception, then if the item descriptors use-local-on-failure attribute is true, the operation returns the value from the local repository. Otherwise, the exception is passed on.
updateItem
The updateItem operation updates the values of the repository items properties both in the local repository and the remote system. The update is handled transactionally, so that if the update of the remote system fails, the change to the local value will not occur. This operation uses the IntegrationRepositoryItemDescriptor.updateRemoteItem() method. If the Integration Repository item descriptor defines a mapping file for the updateItem operation, then the updateItem operation creates a MappingRepositoryItem. If the changed-properties-only attribute is true, then the updateItem operation creates a ChangedPropertyBean. Otherwise, the IntegrationRepositoryItem is used. The input for the updateItem Command is either the IntegrationRepositoryItem, the MappingRepositoryItem, or the ChangedPropertyBean as appropriate. It returns a CommandResult. The updateItem operation checks if there is an external ID in the CommandResult returned by the updateItem Command. If there is, the updateItem operation updates the external ID property of the local repository item with the value. If update-local-with-result is set to true, then the Integration Repository looks in the CommandResult for new property values. Any values that appear in the result will be set on the local value of the item. If the updateRemoteItem call times out, the response depends on the setting of the timeout-response attribute for the updateItem operation. The possible settings are ROLLBACK, INVALID, UNKNOWN, IGNORE.
updateItem and Derived Properties

If your underlying local repository uses the derived properties feature of the SQL repository and you are using the changed-properties-only attribute set to true, then you should define a derived-properties element to specify how the derived properties are handled. The derived-properties element is a container for a list of derived properties mapped to some property that is used in the derivation. It ensures that if the
80
value of a property that is one of the derivation expressions of a derived property is changed, the Integration Repository treats the derived property itself as changed as well. The derived-properties element can optionally be used as a child element of an update-item Tag (page 89). It is a container for one or more property elements, each of which has a name attribute and a referenced-property attribute. The name attribute is the name of a property that can be derived from the referenced-property. The name attribute and referenced-property attribute must both be valid property names defined within the given item descriptor. If changed-properties-only="true" in the update-item element, then whenever the referencedproperty is sent in the update command, the name property will be as well. For example, suppose you have a property named remoteAddress that can be derived from a property named businessAddress. By including this derived-properties element in the update-item element, then whenever the businessAddress property is included as a changed property, the remoteAddress property will also be included as a changed property:
<derived-properties> <property name="remoteAddress" referenced-property="businessAddress"/> </derived-properties>
If you do not configure the derived-properties element for any derived properties in your item, then a change to a derived propertys expression will not cause the derived property itself to appear as a changed property. See SQL Repository Data Models: Derived Properties in the ATG Repository Guide for more information about derived properties.
addItem
The addItem operation adds the item to the local repository and to the remote system. If the addItem operation fails on the remote system, then the item will not be added to the local system. Since the item is being newly added to the remote system, it is impossible to know in advance what value of the external ID is. The addItem operation attempts to set the external ID property with the result of the addItem Command. If the useexternal-id attribute is true, then a change to the ID results in a clone of the item passed into this operation. This operation uses the IntegrationRepositoryItemDescriptor.addRemoteItem() method. The input for add-item Commands is the RepositoryItem being added. If the Integration Repository item descriptor defines a mapping file, then the addItem operation creates a MappingRepositoryItem. Otherwise, the IntegrationRepositoryItem is used. When the addItem Command returns successfully from the remote system, the addItem operation checks if there is an external ID in the CommandResult. If there is, the addItem operation updates the external ID property in the local repository with the ID value. If update-local-with-result is set to true, then the Integration Repository looks in the CommandResult for new property values. Any values that appear in the result will be set on the local value of the item. If the item was cloned, the original item is removed and the new item is returned. If the addRemoteItem call times out, the response depends on the setting of the timeout-response attribute for the addItem operation. The possible settings are ROLLBACK, INVALID, UNKNOWN, IGNORE.
removeItem
The removeItem operation removes the item from the local repository and from the remote system. This operation uses the IntegrationRepositoryItemDescriptor.removeRemoteItem() method. If there
81
is a mapping file defined in the item descriptor, the target name of the external ID property is used. If the useExternalId is false, then the given ID is the local repository item ID. The input for commands executed for remove-item is whatever input is created by IntegrationRepositoryTools.createRemoveCommandInput(). By default this is a map of the external ID property name to the value of the external ID. If you require a more complex command input, extend IntegrationRepositoryTools and override the createRemoveCommandInput() method. If the remove operation in the remote system fails, the local item will not be removed. If the removeRemoteItem call times out, the response depends on the setting of the timeout-response attribute for the removeItem operation. The possible settings are ROLLBACK, INVALID, UNKNOWN, IGNORE.
Mapping
The Oracle ATG Web Commerce Integration Framework provides tools to help you map Oracle ATG Web Commerce repository items to data objects on the remote system. Rather than export all the properties of a repository item in an integration command, you can define a map of repository item properties to attributes of the remote systems data objects. The mapping file controls which properties are sent as input in a Command, and what the external names of those properties are. For details about repository item mapping, see the Repository to XML Data Binding (page 27) chapter.
Persistent Caching
The Integration Framework uses a separate SQL repository to track integration information. This SQL repository is referred to as the persistent cache or the Integration Data repository. This repository exists to track when particular repository item properties have been fetched from the remote system. This lets the Integration Framework limit the frequency with which it needs to access the remote system. The Integration Data repository has a Nucleus address of /atg/integrations/repository/ IntegrationData. You should not need to do anything to configure or use the Integration Data repository. The repository uses a database table named if_integ_data that is created when you install Oracle ATG Web Commerce. The Integration Data repository defines a single item descriptor, named integration-data. For each repository item in the local repository, there is a corresponding repository item in the Integration Data repository. The integration-data item descriptor defines five properties:
Property
itemID
Description The repository ID of the repository item in the local repository that this information applies to. The name of the item descriptor in the local repository that this information applies to.
itemDescriptor
82
Property
repositoryName state
Description The name of the local repository. This property tracks whether the item in the local repository is up to date with the data in the remote system. The state can be one of OK, INVALID, or UNKNOWN. Unless the state is OK, then the Integration Repository tries to get the data from the remote system, rather than relying on the local repository. This property tracks the last time a getItem operation retrieved the items data from the remote system. If the current time minus the lastRun time exceeds the localvalue-timeout value set in the Integration Repository, then this item is marked INVALID and the Integration Repository retrieves the items data from the remote system with a getItem operation.
lastRun
The item descriptor definition in the Integration Repository definition file specifies a local-value-timeout attribute:
<item-descriptor name="my-item" local-value-timeout="1000"/>
The state of a repository item can be set to one of OK, INVALID, or UNKNOWN. The state can be changed if an Integration Repository command returns an error or times out. The Integration Repository checks the state and lastRun values on a get-item operation. If the state is INVALID, or the lastRun time for the given command is more than local-value-timeout milliseconds from the current time, then the item is reloaded from the remote system (using the get-item Command). If an item is transient, then a transient instance of the Integration Data repository item would be created. An item descriptor in the Integration Repository can also define one or more read-only states. If the state of an item in the Integration Data repository is in a read-only state, then the values in the local repository can be used for read-only operations (query, get) but not for write operations (update, add, remove).
Cleaning up the Persistent Cache

The Integration Framework includes a scheduled service named CleanIntegrationData (class atg.adapter.integrations.CleanIntegrationData extends atg.service.scheduler.SingletonSchedulableService). This service is a Nucleus component with the address /atg/integrations/repository/CleanIntegrationData. It is responsible for cleaning up the persistent cache. The CleanIntegrationData service deletes from the Integration Data repository any records that have not been updated since the time specified by its expireTimePeriod property. If its deleteInvalidStateItems property is set to true, then records that are not in the state IntegrationRepository.OK will also be deleted. Note that the corresponding repository items are not deleted from the local repository. The CleanIntegrationData component has the following configurable properties:
Property Name
expireTimePeriod
Description Time in seconds that items remain in the persistent cache after they are last updated.
Default Value 864000 (10 days)
83
Property Name
deleteInvalidStateItems schedule
Description Items are deleted if their state is not OK. See Scheduler Services in the Core Dynamo Services chapter of the ATG Platform Programming Guide for information about how to set schedules in schedulable services.
Default Value true
Configuration Examples
The following examples show some ways to configure three of the alternatives described in the Integration Approaches (page 70) section: Configuring the Remote-Only Model (page 84) Configuring the Remote-then-Local Model (page 85) Configuring the Local-then-Remote Model (page 86)
Configuring the Remote-Only Model

The Remote Only (page 70) model is sketched in the Integration Approaches (page 70) section. In this use case model, the data is maintained only on the remote system. Each time that the Oracle ATG Web Commerce application needs to access the data, a command is issued to the remote system. To configure this integration model, configure your Integration Repository with transient properties. None of the repository item properties will be stored in the local repository database, so there are no table tags defined in the local repository definition file. In addition, the local-value-timeout attribute in the item descriptors of the Integration Repository is set to a small value. For example, the local repository definition might look like this: localRepositoryDefinition.xml
<gsa-template> <item-descriptor name="contact" display-property="lastName"> <property name="id" data-type="string"/> <property name="firstName" data-type="string" display-name="First Name"/> <property name="lastName" data-type="string" display-name="Last Name"/> <property name="email" data-type="string" display-name="Email Address"/> </item-descriptor> </gsa-template>
You can define a mapping file that specifies the names of these properties on the remote system: mapping.xml
<item-descriptor
84
repository-path="/atg/integrations/remotex/RemoteXIntegrationRepository" name="contact"> <property name="id" targetName="Id" include="true"/> <property name="firstName" targetName="First Name" include="true"/> <property name="lastName" targetName="Last Name" include="true"/> <property name="email" targetName="Email Address" include="true"/> </item-descriptor>
The Integration Repository definition file would then look like this: integrationRepository.xml
<integration-repository-template> <item-descriptor name="contact" external-id-property="id" use-external-id="true" mapping-file="/atg/integrations/remotex/mapping.xml" local-value-timeout="1000"> <query command="/atg/integrations/remotex/GetContacts" view-class="atg.integrations.remotex.RemoteXQueryView"/> <get-item command="/atg/integrations/remotex/GetContacts" use-local-on-failure="false"/> <update-item command="/atg/integrations/remotex/UpdateContacts"/> </item-descriptor> </integration-repository-template>
This configuration means that queries and getItem operations use the GetContacts command. Users cannot remove or create contacts in the remote system, since no Command has been defined for these operations, but can update existing ones. If the remote system is unavailable in a getItem operation, then no data is available, since the use-local-on-failure attribute is set to false. Note that you could change this to provide Oracle ATG Web Commerce with read-only access to the remote system by omitting the updateItem Command, leaving only the GetContacts Command to query and get items.
Configuring the Remote-then-Local Model

The Remote then Local (page 70) model is sketched in the Integration Approaches (page 70) section. In this case, the primary source for the data is the remote system. A local copy of the data is maintained in the local repository. Each time that the Oracle ATG Web Commerce application needs to access the data, a command is issued to the remote system. If the command fails to return, then the command is issued to the local repository. To configure this integration model, use persistent properties that are stored through the local repository in a database on the local system. These persistent properties are defined within table tags in the local repository item descriptors. For example: localRepositoryDefinition.xml
<gsa-template> <item-descriptor name="contact" display-property="lastName"> <table name="contact" ... > <property name="id" data-type="string"/> <property name="firstName" data-type="string" display-name="First Name"/> <property name="lastName" data-type="string" display-name="Last Name"/>
85
<property name="email" data-type="string" display-name="Email Address"/> </table> </item-descriptor> </gsa-template>
integrationRepository.xml The Integration Repository definition file uses the local-value-timeout attribute with a small value, so that subsequent attempts to access an item will continue to try the remote system before resorting to the local repository. In addition, the use-local-on-failure attribute for the getItem command is set to true.
<integration-repository-template> <item-descriptor name="contact" external-id-property="id" use-external-id="true" local-value-timeout="1000"> <query command="/atg/integrations/remotex/GetContacts" view-class="atg.integrations.remotex.RemoteXQueryView"/> <get-item command="/atg/integrations/remotex/GetContacts" use-local-on-failure="true"/> <update-item command="/atg/integrations/remotex/UpdateContacts"/> </item-descriptor> </integration-repository-template>
Configuring the Local-then-Remote Model

The Local then Remote (page 71) model is sketched in the Integration Approaches (page 70) section. In this case, a version of the data is maintained in a local repository. Only if the data is not available locally, or if the local copy has expired or otherwise been marked invalid, do we query the remote system for the data. To configure this integration model, use persistent properties that are stored through the local repository in a database on the local system. The local repository is defined pretty much the same way as in the Configuring the Remote-then-Local Model (page 85). The Integration Repository definition is a bit different. It uses the local-value-timeout attribute with a large value, so that items will remain valid in the local repository for a reasonable length of time. integrationRepository.xml
<integration-repository-template> <item-descriptor name="contact" external-id-property="id" use-external-id="true" local-value-timeout="3600000"> <query command="/atg/integrations/remotex/GetContacts" view-class="atg.integrations.remotex.RemoteXQueryView"/> <get-item command="/atg/integrations/remotex/GetContacts" use-local-on-failure="true"/> <update-item command="/atg/integrations/remotex/UpdateContacts" timeout-response="UNKNOWN"/> <add-item command="/atg/integrations/remotex/AddContacts" timeout-response="INVALID"/> <remove-item command="/atg/integrations/remotex/RemoveContacts"/> </item-descriptor> </integration-repository-template>
86
Integration Repository Definition File

The XML definition file for Integration Repositories conforms to the integration-repository Document Type Definition (page 91) with the URL:
http://www.atg.com/dtds/integrations/integration-repository_1.0.dtd
The definition file includes the following elements: integration-repository-template tag (page 87) header tag (page 87) item-descriptor tag (page 87) item-descriptor Child Tags (page 88)
integration-repository-template tag
The integration-repository-template tag acts as a container for the Integration Repository definition file. It contains a single header tag and one or more item-descriptor tags.
header tag
The header tag contains information about the Integration Repository definition file. It can contain the following child elements: name author version description
item-descriptor tag
Each item descriptor in the local repository that is integrated must be defined in the Integration Repository definition file and configured in the item-descriptor tag. This tag has the following attributes:
Attribute
name
Description The name of the item descriptor being configured. This must match the name of the item descriptor in the local repository. This is the default mapping file that is used when sending a repository item to any of the configured commands. The mapping file controls which properties are sent as input, and what the external names of those properties are. See Mapping (page 82).
mapping-file
87
Attribute
external-idproperty
Description Just as there is a local ID (repositoryId) for each item in the local repository, there must also be an ID for each corresponding item in the remote system. This attribute identifies which repository item property in the local repository will be used to store the external ID. The external ID property does not have to be the same property as the repository ID in the local repository. If it is not, set useexternal-id to false. If the local repository ID should match the external ID, then this property should be set to true. If the external ID is just stored as a non-ID property on the local item, then set this property to false. This property configures the number of milliseconds that a local item is valid before it should be retrieved from the external system. For example, if this is set to 600000, and you call getItem, then each subsequent call to getItem for the next 10 minutes will return that same item with no updates. After 10 minutes, a call to getItem will once again execute the getItem command. Each item retrieved from the remote system has a state associated with it in the persistent cache. The state can be one of OK, INVALID, or UNKNOWN. The default value is UNKNOWN. This property identifies which of those states will render the item read-only. This is useful if you timed out on a recent call to getItem and you still want people to be able to view the item but do not want to run the risk of them changing it. See Persistent Caching (page 82). This attribute controls the behavior if there is no configured command for a particular operation. If this attribute is true, then the local repository can act on the local repository item without reference to the remote system. For example, if there is no update-item command configured, and someone calls updateItem, is this an error? Should the update just go to the local repository with no Command execution?
use-external-id
local-valuetimeout
read-only-states
allow-localoperation
item-descriptor Child Tags

The item-descriptor tag has five possible child tags: query Tag (page 88) get-item Tag (page 89) add-item Tag (page 90) update-item Tag (page 89) remove-item Tag (page 90) The operations defined by these tags are also described in the Command Operations (page 79) section.
query Tag
This configures the behavior of the Integration Repository when the executeQuery method is called on the RepositoryView for items of this type.
88
query Tag Attributes

command This is the Nucleus path to the Command implementation that will perform the query of the remote system. view-class If the default view class is not sufficient for querying items of this type, this subclass of atg.adapter.integrations.IntegrationRepositoryView will be used for queries instead. query-cache-size This is the same as the SQL repository attribute of the same name. How many queries will be cached at a time? query-expire-timeout The time in milliseconds that each query cache entry remains valid.
get-item Tag
This configures the behavior of the Integration Repository when getItem is called for repository items of this type.
get-item Tag Attributes

command This is the Nucleus path to the Command implementation that will get the item from the remote system. Usually, the Command for getting is the same as the Command for querying. use-local-on-failure If this attribute is set to true then a locally cached value will be used in cases that the Command fails. For example, if the remote system is unavailable, the locally cached item will be returned to the user. If the remote item has never been retrieved before, this attribute has no effect.
update-item Tag
This configures the behavior of the Integration Repository when updateItem is called for repository items of this type. It can optionally contain a derived-properties Tag (page 90) as a child element. See updateItem and Derived Properties (page 80) in the Command Operations section.
update-item Tag Attributes

command This is the Nucleus path to the Command implementation that will update the item in the remote system. mapping-file If the mapping file that is defined on the item descriptor is insufficient for creating input to the update Command, a different mapping file can be configured here. One common use for this is to exclude read-only properties from the input. timeout-response This defines the behavior in response to a CommandTimeoutException thrown by the update item Command. If this is not set, then the repositorys defaultTimeoutResponse property will be used instead. The possible settings for this attribute are: ROLLBACK, INVALID, UNKNOWN, IGNORE. The default is ROLLBACK. changed-properties-only If this is set to true, then only properties that have changed will be passed to the update item Command. The external-id-property is always included. update-local-with-result
89
If this is set to true, then the Integration Repository will look in the CommandResult for new property values. Any values that appear in the result will be set on the local value of the item. ignore-external-id-change If this is set to true, then if the only changed property on the item is the external ID property, no call to the update item Command will be made.
add-item Tag
This configures the behavior of the Integration Repository when addItem is called for repository items of this type.
add-item Tag Attributes

command This is the Nucleus path to the Command implementation that will add the item to the remote system. mapping-file If the mapping file that is defined on the item descriptor is insufficient for creating input to the add Command, a different mapping file can be configured here. One common use for this is to exclude read-only properties from the input. timeout-response This defines the behavior in response to a CommandTimeoutException thrown by the add item Command. If this is not set, then the repositorys defaultTimeoutResponse property will be used instead. The possible settings for this attribute are: ROLLBACK, INVALID, UNKNOWN, IGNORE. The default is ROLLBACK. update-local-with-result If this is set to true, then the Integration Repository will look in the CommandResult for new property values. Any values that appear in the result will be set on the local value of the item.
remove-item Tag
This configures the behavior of the Integration Repository when removeItem is called for repository items of this type.
remove-item Tag Attributes

command This is the Nucleus path to the Command implementation that will remove the item from the remote system. timeout-response This defines the behavior in response to a CommandTimeoutException thrown by the remove item Command. If this is not set, then the repositorys defaultTimeoutResponse property will be used instead. The possible settings for this attribute are: ROLLBACK, INVALID, UNKNOWN, IGNORE. The default is ROLLBACK.
derived-properties Tag
If your underlying local repository uses the derived properties feature of the SQL repository and you have set changed-properties-only="true" in the update-item element, then you should define a derivedproperties element to specify how the derived properties are handled. The derived-properties element is a container for a list of derived properties mapped to some property that is used in the derivation. The derived-properties element can optionally be used as a child element of an update-item Tag (page 89). See updateItem and Derived Properties (page 80) in the Command Operations section. See also SQL Repository Data Models: Derived Properties in the ATG Repository Guide for more information about derived properties. The derived-properties element contains one or more property tags.
90
property Tag
The property tag in the Integration Repository definition file is a child element of a derived-properties element.
property Tag Attributes

A property tag in a derived-properties element uses the following attributes:
name referenced-property
The name of a property that can be derived from the referenced-property. The name of a derivation expression of a derived property specified by the name attribute.
If changed-properties-only="true" in the update-item element, then whenever the referencedproperty is sent in the update command, the property specified by the name attribute will be as well. See updateItem and Derived Properties (page 80) in the Command Operations section.
integration-repository Document Type Definition

<?xml encoding="UTF-8"?>         <!ENTITY % timeoutresponses "(ROLLBACK|UNKNOWN|INVALID|IGNORE)"> <!ELEMENT integration-repository-template (header?, item-descriptor*)>  <!ELEMENT header (name?, author*, version?, description?)>  <!ELEMENT name (#PCDATA)>  <!ELEMENT author (#PCDATA)>
91
 <!ELEMENT version (#PCDATA)>  <!ELEMENT description (#PCDATA)>
<!-<!-<!-<!- integration-view element: --> The definition of a view as it appears to code that calls the --> integration repository. --> =============================================================== -->
<!ELEMENT item-descriptor (query?, get-item?, update-item?, add-item?, remove-item?)>
<!ATTLIST item-descriptor name CDATA #REQUIRED mapping-file CDATA #IMPLIED external-id-property CDATA #IMPLIED use-external-id CDATA #IMPLIED local-value-timeout CDATA #IMPLIED read-only-states CDATA #IMPLIED allow-local-operation CDATA #IMPLIED > <!ELEMENT query EMPTY> <!ATTLIST query command CDATA #IMPLIED view-class CDATA #IMPLIED query-cache-size CDATA #IMPLIED query-expire-timeout CDATA #IMPLIED > <!ELEMENT get-item EMPTY> <!ATTLIST get-item command CDATA #IMPLIED use-local-on-failure CDATA #IMPLIED > <!ELEMENT update-item (derived-properties?)> <!ATTLIST update-item command CDATA #IMPLIED mapping-file CDATA #IMPLIED timeout-response %timeoutresponses; "ROLLBACK" changed-properties-only CDATA #IMPLIED update-local-with-result CDATA #IMPLIED ignore-external-id-change CDATA #IMPLIED > <!ELEMENT derived-properties (property+)> <!ELEMENT property EMPTY> <!ATTLIST property
92
name CDATA #REQUIRED referenced-property CDATA #REQUIRED > <!ELEMENT add-item EMPTY> <!ATTLIST add-item command CDATA #IMPLIED mapping-file CDATA #IMPLIED timeout-response %timeoutresponses; "ROLLBACK" update-local-with-result CDATA #IMPLIED > <!ELEMENT remove-item EMPTY> <!ATTLIST remove-item command CDATA #IMPLIED timeout-response %timeoutresponses; "ROLLBACK" >
93
94
Remote Procedure Calls
The integration framework includes a facility for making remote procedure calls (RPC). The Integration Repository makes extensive use of RPC to make calls to the remote system for querying and data synchronization. The RPC facility is designed to be as generic as possible in order to support a variety of remote systems and middleware transports. The classes and interfaces in the atg.integrations package provide an API that can be implemented in various ways to work with Web Services, the Java Connector Architecture (JCA), or different middleware transports. For example, the Oracle ATG Web Commerce Tibco Adapter includes an implementation of the RPC API that enables the Oracle ATG Web Commerce platform to execute Tibco commands. This chapter discusses the following topics: RPC API Architecture (page 95) Implementing the RPC API (page 97) Executing Commands in Pages (page 98)
RPC API Architecture

The core pieces of the Oracle ATG Web Commerce RPC API architecture are: atg.integrations.Command interface generic representation of a command atg.integrations.CommandHandler interface executes a command, and performs pre- or postprocessing atg.integrations.CommandResult class encapsulates the results of a command To implement the RPC API, you create classes that implement the Command or CommandHandler interface, and return CommandResult objects. This section discusses the expected behavior of these classes. Note that some of this behavior is not enforced by the interfaces, but is nonetheless required by the API. For additional information about Command, CommandHandler, and CommandResult, see the ATG Platform API Reference.
Command Interface
The atg.integrations.Command interface is a generic representation of a command. You create specific commands by implementing this interface.
9 Remote Procedure Calls
95
The Command interface has two methods for executing commands, execute() and invokeRPC(). Both of these methods take a java.lang.Object as input (to be as generic as possible), and return a CommandResult. The execute() method is the one actually called by an application. Invoking this method sets off a chain of actions that ultimately results in the invokeRPC() method being executed. The invokeRPC() method does the actual work of making a call to the remote system. Note, however, that applications should not call this method directly, as the processing of commands is based on the assumption that execute() is called first. The Command.execute() method must implement the following logic: If the Command points to a CommandHandler (that is, if the Command.commandHandler property is not null), pass the Command and its input to that CommandHandler by calling the CommandHandler.executeCommand() method. If the Command does not point to a CommandHandler, call the Command.invokeRPC() method.
CommandHandler Interface
The atg.integrations.CommandHandler interface is a generic representation of a handler class for preprocessing and postprocessing commands. Command handlers are not a required part of the RPC API, since a Command.execute() method can call the corresponding Command.invokeRPC() method directly. However, command handlers add a great deal of power and flexibility to the RPC system. To pass a Command and its input to a CommandHandler, the Command.execute() method calls the CommandHandler.executeCommand() method. The CommandHandler.executeCommand() method must implement the following logic: If the CommandHandler points to another CommandHandler (that is, if the CommandHandler.nextCommandHandler property is not null): Perform any preprocessing. Pass along the Command and its input to the next CommandHandler by calling CommandHandler.getNextCommandHandler().executeCommand(). Perform any postprocessing. If the CommandHandler does not point to another CommandHandler: Perform any preprocessing. Execute the Command.invokeRPC() method. Perform any postprocessing. This logic allows command handlers (and the services they implement) to be chained together. The final CommandHandler in the chain must be able to call the Command.invokeRPC() method, to ensure that the command can be executed. However, it is not required that the command is always executed. For example, one typical use for a command handler is caching of commands and their results. Such a command handler might work like this: Examine the command to determine if it is in the cache. If the command is in the cache, return the cached result. If the command is not in the cache, execute the command, return the result, and cache the command and result.
96
CommandResult Class
When a Command or CommandHandler object executes a Command, it must return a CommandResult. A CommandResult is just a container that has two other objects as properties: The result property is a java.lang.Object that is the actual object returned by the remote call. The context property is a java.util.Map that can be used to store additional parameters and their values. Application code should access the results in the result object by using the DynamicBeans API. For example, suppose the RPC call adds two integers and stores the result as an integer named sum. The application code could obtain the value of sum like this:
Integer sum = (Integer) DynamicBeans.getPropertyValue(getCommandResult.getResults(),"sum");
The DynamicBeans API is recommended because it eliminates the need to convert the object returned from the transport RPC into a generic data format, which requires additional memory and processing time. For example, if a query returns a DOM object, the DynamicBeans API can be used to access the data directly from it, avoiding the need to copy the properties from the DOM object to another object type (such as a Map). RPC implementations are not required to use the context Map. It is included in the CommandResult object to provide a way to store additional information that is not part of the result object.
Implementing the RPC API

As mentioned above, the RPC API is intended to be as generic as possible so implementations can support a wide variety of transports and remote systems. However, this flexibility also puts a lot of burden on the implementer. To simplify the process, the atg.integration package includes basic implementations of the Command and CommandHandler interfaces. Rather than implementing the interfaces directly, you can just extend the BaseCommand and BaseCommandHandler classes. The atg.integrations.BaseCommand class provides an execute() method that implements the logic described in the Command Interface (page 95) section above. Classes that extend this class must provide their own implementations of the invokeRPC() method. The atg.integrations.BaseCommandHandler class provides an executeCommand() method that implements the logic described in the CommandHandler Interface (page 96) section above. Classes that extend this class can override the executeCommand() method to do their pre- or postprocessing as needed. Implementing this method can be simplified by having the executeCommand() method of the subclass call the executeCommand() method of the parent class while adding pre- or postprocessing of its own. For example, a CachingCommandHandler class might look like this:
Public class CachingCommandHandler extends BaseCommandHandler { Map sCache = new HashMap(); // Cache of method invocations. Public CommandResult executeCommand(Command pCommand, Object pInput) { if (sCache.containsKey(pInput)) { return sCache.get(pInput); } else {
97
CommandResult result = super.executeCommand(pCommand, pInput); sCache.put(pInput, result); return result; } } }
For more information about BaseCommand and BaseCommandHandler, see the ATG Platform API Reference.
Exception Handling
The Command.execute(), Command.invokeRPC(), and CommandHandler.executeCommand() methods must throw exceptions of class atg.integration.CommandInvocationException. This exception is intended to wrap any underlying exceptions that might be thrown by a particular transport or remote system. This exception must wrap the underlying exception, rather than copying its message, so that stack trace printouts include the information from the underlying exception. The CommandInvocationException class has two useful subclasses: atg.integration.CommandTimeoutException can be thrown when an RPC call times out. This is a special case, since a timeout doesnt indicate whether the RPC call succeeded or not. atg.integration.InvalidInputException can be thrown if the input object passed to the Command is invalid.
Executing Commands in Pages

You can use the atg.integrations.MapRPCDroplet servlet bean to execute RPC commands in JavaServer Pages. This servlet bean executes a command and, depending on whether the command is executed successfully, renders either its output open parameter or its error open parameter. If the command is executed successfully, the result output parameter is set to the result of the command, and the output open parameter is rendered. If an exception is thrown, the exception output parameter is set to the exception, and the error open parameter is rendered. The command input parameter takes an object that implements the atg.integrations.Command interface. The inputParameters parameter supplies the inputs to the command as a java.util.Map of parameter name/value pairs. As an alternative to specifying these values in pages, MapRPCDroplet has command and inputParameters properties that you can use to specify these values in the servlet beans properties file. Note, however, that you cannot specify the same parameter both in the properties file and in a page. If you do this, MapRPCDroplet throws a ServletException.
MapRPCDroplet also takes an inputParameterNames parameter that you can use to specify the input names
as a list of page parameters, and then use those page parameters to specify the input values. For example:
<dsp:param name="inputParameterNames" value="first_name,age"/> <dsp:param name="first_name" value="Bill"/> <dsp:param name="age" value="43"/>
98
You cannot include both the inputParameters and the inputParameterNames parameter in the same page, or include inputParameterNames in the page if inputParameters is specified in the servlet beans properties file. However, there is a way you can specify default values for the command parameters in the servlet beans properties file, and then optionally override these values in pages. To do this: Use the inputParameters property to specify the command parameters and their default values. In your pages, define page parameters with the same names as the command parameters. The values specified for the page parameters override the values in the properties file, and are used when the command is invoked. If a command parameter has no corresponding page parameter, the default value from the properties file is used.
Input Parameters
command The command to execute. Must be an instance of a class that implements the atg.integrations.Command interface. This parameter can either be defined in a page or by setting the command property of the servlet bean, but it cannot be defined both ways. inputParameters The inputs to pass to the command, supplied as a java.util.Map of parameter name/value pairs. This parameter can either be defined in a page or by setting the inputParameters property of this servlet bean, but it cannot be defined both ways. inputParameterNames A comma-separated list of command input parameter names. Each name defines a page parameter whose name and value (specified in the page) are used to supply one of the inputs to the command. parameter names Page parameters that correspond to the names of command input parameters specified in inputParameterNames.
Output Parameters
result The result object from the command, if the execution is successful. exception The exception thrown by the command, if the execution is unsuccessful.
Open Parameters
output Rendered if the command is executed successfully. error Rendered if the command throws an exception.
Example
The following example uses inputParameterNames to create a UserId page parameter, and then sets its value to the value of a profile ID. This parameter name/value pair is passed as an input to the command. Depending
99
on whether the command is executed successfully, Dynamo renders either the output open parameter or the error open parameter.
<dsp:droplet bean="/atg/integrations/MapRPCDroplet"> <dsp:param name="command" value="bean:/atg/integrations/jdbc/QueryForUser"/> <dsp:param name="inputParameterNames" value="UserId"/> <dsp:param name="UserId" value="bean:Profile.Id"/> <dsp:oparam name="output"> <p>The user's email address is: <dsp:valueof param="result.emailAddress"/> </dsp:oparam> <dsp:oparam name="error"> <p>Unable to execute query. The following exceptions occurred: <dsp:valueof param="exception"/> </dsp:oparam> </dsp:droplet>
100
Part III. ATG Platform REST Web Services

This section provides information about and instructions for using the Oracle ATG Web Commerce platform Representational State Transfer (REST) Web Services. See basic information about using the REST Web Services interface in Using REST Web Services (page 103). The REST Web Services provide access to Nucleus components. Nucleus components are server-side JavaBeans and servlets that perform the back-end functionality of a Web applicationfor example, enabling database connectivity, logging, scheduling, and handling HTTP requests. The Oracle ATG Web Commerce platform REST Web Services expose methods that get component data and get and set component property values. You cannot use the Oracle ATG Web Commerce platform REST Web Services to delete components. See instructions for specific operations in the following sections. Working with Component Properties (page 139) Invoking Component Methods (page 143) Invoking Form Handlers (page 145) Working with Repositories (page 155) Note: The Oracle ATG Web Commerce platform REST Web Services are not related to the SOAP Web Services described previously in this guide. The REST and SOAP modules do not share any functionality. The two technologies were developed independently and are quite different in their implementations.
10 Using REST Web Services
This section provides general information about and instructions for using the Oracle ATG Web Commerce platform REST Web Services interface. You must do the following before you can use the REST Web Services. 1. Start the REST module on the Oracle ATG Web Commerce platform server. See Starting the REST module (page 104). 2. Configure the security settings to give at least one user permission to use REST Web Services. See Security for REST Web Services (page 179). 3. Log in to the REST Web Services server and configure your HTTP client software to pass the session ID to the server with each HTTP request. See Logging In (page 108). The following diagram shows components of the REST Web Services interface and the sections of this document that explain them.
1. Starting the REST module (page 104) 2. Configuring the REST Server (page 173) 3. Security for REST Web Services (page 179) 4. HTTP Requests (page 104) 5. Input Values (page 118) 6. Returned Data (page 126)
103
7. Errors and Exceptions (page 135) 8. Client Software (page 106) 9. ATG Client Libraries (page 183)
Starting the REST module

To use the REST Web Services, include the REST module in your Oracle ATG Web Commerce platform server. See information about assembling Oracle ATG Web Commerce applications in the ATG Platform Programming Guide. The following example shows a screen from the Configuration and Installation Manager (CIM) that edits the list of modules included in a server. See information about using CIM in the ATG Installation and Configuration Guide.
-------MODULE LIST EDITOR OPTIONS----------------------------------------------enter [h]elp, [m]ain menu, [q]uit to exit
Current Module List: DafEar.Admin, DPS, DSS, Service.SelfService, DAF.Search.Routing, ARF.base, DAF.Search.Base.QueryConsole, REST
*[A] [R] [D] >
Add A Custom Module Remove A Custom Module Done
HTTP Requests
This section provides information about the HTTP requests that you can send to the REST Web Services running on an Oracle ATG Web Commerce platform server.
REST Web Services URLs

The URLs for Oracle ATG Web Commerce platform REST Web Services are the locations to which you address HTTP requests. URLs are central to REST Web Services and you will access different components and functions of the Oracle ATG Web Commerce platform using the specific URL for each one. The application path in the Oracle ATG Web Commerce platform REST Web Service URLs starts with /rest/. The application path is the portion of a URL that follows the hostname and port number. For example, you can use the following URL to request the value of the running property of the atg/dynamo/Configuration component.
http://servername:port/rest/bean/atg/dynamo/Configuration/running
104
The portion of the application path following /rest/ identifies the specific component you are addressing. This part of the URL is based on the component pathnames of Nucleus components and repository items. See information about component paths in the ATG Platform Programming Guide.
Nucleus Components
The URL for addressing a Nucleus component with the REST Web Services includes /bean/ in its application path. The following example shows the beginning of the URL for a Nucleus component.
http://servername:port/rest/bean/
You can invoke methods and get or set property values of Nucleus components. Include the names of methods and properties in the application path of the component. Separate the name of the method or property with a forward slash as if it were a separate container. For example, the following URL addresses the running property of the atg/dynamo/Configuration component.
http://servername:port/rest/bean/atg/dynamo/Configuration/running
See information about performing operations with Nucleus component properties and methods in Working with Component Properties (page 139) and Invoking Component Methods (page 143).
Repositories
The URL for addressing a repository item with the REST Web Services includes /repository/ in its application path. The following example shows the beginning of the URL for a repository item.
http://servername:port/rest/repository/
You can address specific repository items and get or set repository item property values. Include the names of repository items and values in the application path. Separate the names and values with a forward slash as if it were a separate container. For example, the following URL addresses the user repository item in the ProfileAdapterRepository repository.
http://servername:port/rest/repository/atg/userprofiling/ ProfileAdapterRepository/user
The following URL addresses a specific user record in the user repository item. The value of the id property at the end of the path indicates which user.
http://servername:port/rest/repository/atg/userprofiling/ ProfileAdapterRepository/user/210002
The following URL addresses a specific property of a user record in the user repository item.
http://servername:port/rest/repository/atg/userprofiling/ ProfileAdapterRepository/user/210002/login
See information about performing operations with repositories in Working with Repositories (page 155).
105
Client Software
You can use any means of transmitting HTTP requests to the ATG platform REST Web Services that you wish. Any client software that is capable of sending and receiving messages via HTTP will be adequate. Select the client software that you use according to the requirements of your environment.
ATG Clients for the REST Web Services

Oracle ATG Web Commerce provides two client libraries that you can use to interact with the Oracle ATG Web Commerce platform REST Web Services. These clients make the REST Web Services easier to use by hiding all the complexity of creating connections, assembling payloads for requests, and processing responses. See information about the clients in ATG Client Libraries (page 183).
Curl Command Line Tool in Documentation Examples

The examples in this document use the Curl command-line tool to send and receive HTTP messages. Curl is shown in these examples because its command-line invocation shows the input and the HTTP activity that takes place when using the Oracle ATG Web Commerce platform REST Web Services. See information about the Curl command-line tool at http://curl.haxx.se/. Note: You can use any client software to exchange HTTP messages with the Oracle ATG Web Commerce platform REST Web Services. You are not required or encouraged to use the Curl command-line tool. Note: Oracle ATG Web Commerce is not associated with the makers of the Curl command-line tool in any way. Find all information about the tool and its makers at http://curl.haxx.se/. The examples in this document include several command-line flags. These flags configure the behavior of the Curl command-line tool as it makes HTTP requests. The flags are included in examples to better show the HTTP requirements of the Oracle ATG Web Commerce platform REST Web Services interface and to help you reproduce the examples if you choose to do so. The following example shows a typical invocation of the Curl command-line tool. The components of the command are explained in the table below.
curl -v \ -b cookies.txt \ -X PUT \ -H "Content-Type: application/xml" \ -d "<parameters><middleName>Desire</middleName></parameters>" \ http://servername:port/rest/repository/atg/userprofiling/ ProfileAdapterRepository/user/300001
Command Component
curl
Explanation Names the program being invoked. The manner in which you invoke the Curl command-line tool depends on the way it has been installed in your environment. Write verbose output while sending and receiving HTTP messages. This option exposes more details of the HTTP transaction.
-v
106
Command Component
-b
Explanation Use cookies stored in the specified file to authenticate the client. This example specifies that cookies are stored in a file named cookies.txt. A session identifier must be stored in the file. When Curl logs into the REST Web Services, the -c cookies.txt instructs it to write the cookies it receives in that file. See Logging In (page 108).
-X
Use the specified HTTP method when communicating with the REST Web Services. This example specifies that Curl should use the PUT method. Include the specified Content-Type declaration in the HTTP request header. This describes the nature of the data in the message body of the HTTP request. See Setting the Content-Type Value (page 117). Include the following content in the message body of the HTTP request. This example includes XML parameters in the message body. The URL of the Oracle ATG Web Commerce platform REST Web Service that is used in the example. See REST Web Services URLs (page 104).
-H
-d
URL
Note: The HTTP transactions shown in the examples in this document may include specific details of the testing environment used to produce them. Some details may differ in the HTTP transactions you conduct with the Oracle ATG Web Commerce platform REST Web Services. For example, the application server version identifiers shown in the HTTP transaction may not match the application that your Oracle ATG Web Commerce platform server uses.
HTTP Methods
The Oracle ATG Web Commerce platform REST Web Services support the standard HTTP methods. These methods are described in the following table.
Method GET
Explanation Use this method to return data. Examples of the values you may get are repository item and Nucleus component property values, RQL query results, repository items, and Nucleus components.
107
Method POST
Explanation Use this method to invoke functionality or make changes to your Oracle ATG Web Commerce platform server. For example, you may invoke methods, update Nucleus component properties, and create repository items. The REST Web Services server will treat POST requests as different methods if you include certain control parameters. See Handling POST Requests as Other Methods (page 108).
PUT
Use this method to make changes to your Oracle ATG Web Commerce platform server. For example, you may update repository item and Nucleus component property values.
DELETE
Use this method to remove repository items.
Handling POST Requests as Other Methods

In some situations you may need to submit a POST HTTP request when an operation requires a different method. The REST Web Services server recognizes control parameters that alter the way that it handles POST requests. See information about control parameters in Control Parameters (page 112). Use the atg-rest-http-method control parameter to process an HTTP POST request as a GET, PUT, or DELETE request. This allows you to perform operations that require GET, PUT, or DELETE methods even if your client software cannot send HTTP messages with them. For example, you can include message body data with an HTTP POST request but have the server process it as if it were an HTTP GET request.
Logging In
Before you can use the Oracle ATG Web Commerce platform REST Web Services you must log in to open an authorized HTTP session. When the server receives a log in request for a valid user account, it will authenticate the user and return a session identifier if the authentication is successful. The procedure for logging in to the REST Web Services server is different for external and internal users. See specific procedures with examples in Logging In as an External User (page 109) and Logging In as an Internal User (page 110).
Handling Session Identifiers

When you successfully log in to the REST Web Services server, it will return a session identifier with its HTTP response. The HTTP client that you use must present that session identifier each time it interacts with the REST Web Services server. One method for handling the session identifier is to allow the server to set it in a cookie file for the client.
108
The specific procedure you use to handle the session identifier depends on the client software you are using. The examples in Logging In as an External User (page 109) and Logging In as an Internal User (page 110) show how one HTTP client stores the session identifier in a cookie file.
Logging In as an External User

Invoke the /atg/userprofiling/ProfileServices.loginUser method to log in to the REST Web Services server as an external user. Supply your username and password as functional parameters with the HTTP POST request. Use the positional parameter name arg1 for the username and arg2 for the password. See information about functional parameters and invoking methods in Functional Parameters (page 115) and Invoking Component Methods (page 143).
Success and Failure Responses for External User Log In

If your attempt to log in is successful, the REST Web Services server will return the identifier of the user account in an HTTP response with status code 200 OK. For example, <atgResponse>120001</atgResponse>. If your attempt to log in fails, the server will return a null value in an HTTP response with status code 200 OK. For example, <atgResponse/>. Note: the server returns status code 200 OK in both conditions. Make sure you examine the response value to determine whether an attempt to log in succeeded.
Example of Logging in as an External User

The following example shows an HTTP request to open a REST Web Services session as an external user. The server returns a session identifier in the field labeled JSESSIONID.
curl -v -c cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>MyUsername</arg1><arg2>MyPassword</arg2></parameters>" \ http://myserver:8080/rest/bean/atg/userprofiling/ProfileServices/loginUser * * * > > > > > > > < < < * * < < About to connect() to myserver port 8080 (#0) Trying 12.34.567.890... connected Connected to myserver (12.34.567.890) port 8080 (#0) POST /rest/bean/atg/userprofiling/ProfileServices/loginUser HTTP/1.1 User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 Host: myserver:8080 Accept: */* Content-Type: application/xml Content-Length: 71
HTTP/1.1 200 OK Server: Apache-Coyote/1.1 X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 Added cookie JSESSIONID="7978B952714AB08BEB006A348A25ADB0" for domain myserver, path /, expire 0 Set-Cookie: JSESSIONID=7978B952714AB08BEB006A348A25ADB0; Path=/ X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9y bUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= * Added cookie DYN_USER_ID="120001" for domain myserver, path /, expire 1290872360 < Set-Cookie: DYN_USER_ID=120001; Expires=Sat, 27-Nov-2010 15:39:20 GMT; Path=/
109
* Added cookie DYN_USER_CONFIRM="bca3eb6c2cdeb0e4a625c7165a088e2e" for domain myserver, path /, expire 1290872360 < Set-Cookie: DYN_USER_CONFIRM=bca3eb6c2cdeb0e4a625c7165a088e2e; Expires=Sat, 27Nov-2010 15:39:20 GMT; Path=/ < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Thu, 28 Oct 2010 15:39:20 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse>120001</atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
Logging In as an Internal User

Invoke the Login operation of the /atg/userprofiling/InternalProfileFormHandler component to log in to the REST Web Services server as an internal user. Supply your username and password as functional parameters with the HTTP POST request. Use the parameter name value.login for the username and value.password for the password. See information about functional parameters and invoking form handler components in Functional Parameters (page 115) and Invoking Form Handlers (page 145) . Include the atg-rest-return-form-handler-exceptions control parameter when you invoke this form handler. This will cause the server to return exceptions that occur during the log in operation. If you do not include this control parameter, you will not be able to distinguish between a successful attempt to log in and one that fails. See Success and Failure Responses for Internal User Log In (page 110).
Success and Failure Responses for Internal User Log In

Make sure you include the atg-rest-return-form-handler-exceptions control parameter when you invoke /atg/userprofiling/InternalProfileFormHandler/login. If you do not use this control parameter, you will not be able to distinguish between a successful log in attempt and one that fails. See Control Parameters (page 112). If your attempt to log in is successful, the REST Web Services server will return a response with no exceptions and the HTTP status code 200 OK. For example:
<atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class> <exceptions/> <result>true</result> </atgResponse>
If your attempt to log in fails, the server will return the exceptions encountered in an HTTP response with status code 200 OK. For example:
<atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class> <exceptions> <formExceptions>
110
<element>The password is incorrect</element> </formExceptions> </exceptions> <result>true</result> </atgResponse>
Note: the server returns status code 200 OK in both conditions. Make sure you examine the response value to determine whether an attempt to log in succeeded.
Example of Logging in as an Internal User

The following example shows an HTTP request to open a REST Web Services session as an internal user. The server returns a session identifier in the field labeled JSESSIONID.
curl -v -c cookies.txt -X POST \ -H "Content-Type: application/json" \ -d "{ value.login=MyInternalUsername , value.password=MyInternalPassword }" \ http://myserver:8280/rest/bean/atg/userprofiling/InternalProfileFormHandler/login?atgrest-return-form-handler-exceptions=true * About to connect() to myserver port 8280 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8280 (#0) > POST /rest/bean/atg/userprofiling/InternalProfileFormHandler/login?atg-rest-returnform-handler-exceptions=true HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8280 > Accept: */* > Content-Type: application/json > Content-Length: 70 > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 * Added cookie JSESSIONID="09FA8F5B4B8A4C1A1E97480A91BA7EB8" for domain myserver, path /, expire 0 < Set-Cookie: JSESSIONID=09FA8F5B4B8A4C1A1E97480A91BA7EB8; Path=/ < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAsU2VhcmNoLzEwLjAg WyBQbGF0Zm9ybUxpY2Vuc2UvMCBT ZWFyY2hBZG1pbkxpY2Vuc 2UvMCBQdWJsaXNoaW5nTGljZW5zZS8wIEIyQ0xpY2Vuc2UvMCAgXQ== < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Thu, 28 Oct 2010 20:57:22 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class> <exceptions/> <result>true</result> </atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
111
Logging Out
You can log out to end your Oracle ATG Web Commerce platform REST Web Services session. After you log out, no client will be able to perform REST Web Services operations using the session ID that you present with the log out request. Invoke the /atg/userprofiling/ProfileServices.logoutUser method to log out of the REST Web Services server. Use the HTTP POST method. The following example shows an HTTP request to log out of a REST Web Services session.
curl -v -b cookies.txt -X POST \ http://myserver:8080/rest/bean/atg/userprofiling/ProfileServices/logoutUser * * * > > > > > > < < < < About to connect() to myserver port 8080 (#0) Trying 12.34.567.890... connected Connected to myserver (12.34.567.890) port 8080 (#0) POST /rest/bean/atg/userprofiling/ProfileServices/logoutUser HTTP/1.1 User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 Host: myserver:8080 Accept: */* Cookie: DYN_USER_ID=120001; JSESSIONID=51B1124DFFC8293CF42ACA8AF2D88324; DYN_USER_CONFIRM=bca3eb6c2cdeb0e4a625c7165a088e2e
HTTP/1.1 200 OK Server: Apache-Coyote/1.1 X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY 2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Thu, 28 Oct 2010 20:41:00 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse>void</atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
Control Parameters
Include control parameters with HTTP requests to alter the way that the Oracle ATG Web Commerce platform REST Web Services handle them. For example, if you would like the server to include an identifying string in the response you can use the atg-rest-user-input control parameter to specify that identifying string. You can include control parameters either in the URL for the REST Web Service or in the message body of a POST or PUT request. See URL Parameters (page 116) and Message Body Parameters (page 116). Note: Several control parameters have equivalent configuration properties. Set these configuration properties to control the way that REST Web Services are processed by default. See Configuring the REST Server (page 173).
112
Control Parameter Reference

The following table explains the control parameters recognized by the REST Web Services server.
Parameter
atg-rest-appendmulti-values
Explanation Use this parameter to control whether setting a value on a repository item property will add the value to an existing set of values or replace them. This only applies to repository item properties that hold multiple values. See Appending Values to Repository Item Properties (page 120). For requests which return an array or ordered list, adding this parameter with an integer value allows the caller to specify the number of elements to return. Used with atg-rest-index. Use this parameter to specify the container and element Java classes for nested object property values. See Nested Multiple Value Objects in Input (page 122). Use this parameter to specify a Java class when you are setting an object property value. See Object Values in Input (page 121). The number of references to traverse when rendering output. By default it is zero which causes only the top level object to be returned. Use this parameter to specify which form handler values should be processed first. See Form Value Priority (page 148). Use this parameter to send the REST Web Server a POST HTTP request but have it process the request as if it used a different HTTP method. For example you can use this control parameter to include message body data in a POST HTTP request but have the server process the request as if it used the GET method. Set the value of this parameter to GET, PUT, or DELETE.
atg-rest-count
atg-rest-classdescriptor
atg-rest-class-type
atg-rest-depth
atg-rest-form-tagpriorities atg-rest-http-method
atg-rest-index
Use this parameter to specify the entry in an array or ordered list that will be the starting point when that array or ordered list is returned by the server. Set the value of the parameter to the integer value of the starting position. Use this parameter with atg-rest-count.
atg-rest-input
Use this parameter to override the default input format configured for the server. Set the value of this parameter to json or xml.
atg-rest-json-input
Use this parameter to control whether the REST Web Services server will accept standard JSON markup for setting collection or map values on repository item properties. See JSON Markup Input for Multiple Value Repository Item Properties (page 121).
113
Parameter
atg-rest-method
Explanation Use this parameter to specify the Java method signature when calling an overloaded method. This parameter is only needed if two or more instances of the overloaded method have the same number of arguments.
atg-rest-null
Use this parameter to set the value of a component or repository item property to null. Set the property and include this parameter as the new value. See Setting Properties to Null (page 124). Use this parameter to override the default output format configured for the server. See Choosing Output Markup (page 126). Set the value of this parameter to json or xml. Use this parameter to specify the Java classes for multiple values in JSON functional parameters. The atg-rest-param-class-types parameter includes three components, container-class, element-class, and keyclass. For example, if a functional parameter is a java.util.ArrayList<String>, set the atg-rest-param-class-types as shown below.
{'container-class':'java.util.ArrayList','elementclass':'java.lang.String'}
atg-rest-output
atg-rest-param-classtypes
Use the key-class attribute when the container-class implements java.util.Map. For example
{'container-class':'java.util.HashMap','keyclass':'java.lang.String','elementclass':'java.lang.String'}
See Specifying Java Classes for Multiple Value Input (page 119).
atg-rest-propertyfilter-templates atg-rest-propertyfilters atg-rest-return-formhandler-exceptions
Use this parameter to apply property filter templates to individual REST Web Services Requests. See Filtering Templates (page 168). Use this parameter to apply property filtering to individual REST Web Services Requests. See Filtering for One Request (page 169). Use this parameter to specify that the REST Web Services server should return exceptions it encounters when invoking form handlers in the HTTP response. See Returning Form Handler Exceptions (page 146). Use this parameter to specify that the REST Web Services server should return the properties of the form handler objects it invokes in the HTTP response. See Returning Form Handler Properties (page 147). Include RQL query strings in this parameter. See Performing RQL Queries (page 158). Include this parameter to cause the server to return OK (200) for success rather than CREATED (201) or GONE (410).
atg-rest-return-formhandler-properties
atg-rest-rql
atg-rest-simpleresponse-codes
114
Parameter
atg-rest-transient
Explanation Use this parameter to create transient repository items. Include the parameter with the value true with a REST Web Services request to create a repository item. See Transient Items (page 161). Use this parameter to specify an identifying string that the REST Web Services server will include in the HTTP response. See Identifying a Response (page 128).
atg-rest-user-input
Functional Parameters
Functional parameters provide data that is required by the Oracle ATG Web Commerce platform REST Web Services operation you are performing. For example, if you are setting a property value, the new value is a functional parameter of the operation. You can include functional parameters either in the URL for the REST Web Service or in the message body of a POST or PUT request. See URL Parameters (page 116) and Message Body Parameters (page 116). The functional parameters you provide for a REST Web Services operation depend on the nature of that operation. When invoking a method, you may supply arguments to it. When invoking a form handler, you will supply the form field values. When setting a repository item property value, you will supply the new value. The functional parameters for each operation are explained in the procedures for those operations. See operational procedures in the following sections. Working with Component Properties (page 139) Invoking Component Methods (page 143) Working with Repositories (page 155)
Positional Parameters
Some Oracle ATG Web Commerce platform REST Web Services operations require parameters that are not named. For example, if you invoke the loginUser method of the /atg/userprofiling/ProfileServices component you must pass in two positional arguments. The first is the login value for a user and the second is the password value for that user. The REST Web Services server uses a convention to name positional parameters. It expects the first positional parameter to be named arg1, the second to be named arg2, and any further parameters to be named similarly. The URL parameters in the following REST Web Services URL contain positional parameters that are passed to the loginUser method.
http://servername:port/rest/bean/atg/userprofiling/ProfileServices/loginUser? arg1=MyUsername&arg2=MyPassword
The REST Web Services server will call the loginUser method with the arguments in the positional parameters arg1 and arg2 in that sequence. The method definition for loginUser is shown below. See information about invoking methods in Invoking Component Methods (page 143).
115
public String loginUser(String pLogin, String pPassword) throws ServletException
URL Parameters
You can include control and functional parameters in the URL for Oracle ATG Web Commerce platform REST Web Services. Use standard URL query string syntax and URL encoding if needed. The following example shows a URL with two functional parameters and a control parameter.
http://servername:port/rest/bean/atg/userprofiling/ProfileServices/loginUser? arg1=MyUsername&arg2=MyPassword&atg-rest-user-input=MyMessageId
Message Body Parameters

You can include control and functional parameters in the HTTP message body of an Oracle ATG Web Commerce platform REST Web Services request. The following HTTP request includes two functional parameters and a control parameter in its message body. The content in the message body is specified by the -d flag in this Curl command. See Curl Command Line Tool in Documentation Examples (page 106).
curl -v -c cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>MyUsername</arg1><arg2>MyPassword</arg2><atg-rest-userinput>MyMessageId</atg-rest-user-input></parameters>" http://servername:8080/rest/bean/ atg/userprofiling/ProfileServices/loginUser
The REST Web Services server can interpret message body parameters in one of the following three markup formats. Make sure you set the correct Content-Type value for the markup that you use. See Setting the Content-Type Value (page 117). XML, see XML Parameter Markup (page 117). JSON, see JSON Parameter Markup (page 118). URL query string, see URL Query String Parameter Markup (page 118). The REST Web Services server will only accept parameters in the message body of a POST or PUT HTTP request. If you need to use the GET or DELETE methods, you need to include data with your request, and you cannot include URL parameters, use the atg-rest-view and atg-rest-http-method control parameters. See Handling POST Requests as Other Methods (page 108).
116
Setting the Content-Type Value

Set the Content-Type value when you send an HTTP message with parameters in its message body. The Oracle ATG Web Commerce platform REST Web Services server uses this value to determine how to interpret the parameters. If you do not include the Content-Type or include a value that doesnt match the markup of your parameters, the server will ignore the message body. Use one of the following Content-Type values to specify the markup of the parameters in a message body. Content-Type: application/xml Content-Type: application/json Content-Type: application/x-www-form-urlencoded The following example shows an HTTP request that sets its Content-Type to application/xml.
curl -v -c cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>MyUsername</arg1><arg2>MyPassword</arg2><atg-rest-userinput>MyMessageId</atg-rest-user-input></parameters>" http://servername:8080/rest/bean/ atg/userprofiling/ProfileServices/loginUser * * * > > > > > > About to connect() to servername port 8080 (#0) Trying 12.34.567.890... connected Connected to servername (12.34.567.890) port 8080 (#0) POST /rest/bean/atg/userprofiling/ProfileServices/loginUser HTTP/1.1 User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 Host: servername:8080 Accept: */* Content-Type: application/xml Content-Length: 125
XML Parameter Markup

You can use eXtensible Markup Language (XML) to format parameters in the message body of an Oracle ATG Web Commerce platform REST Web Services request. Enclose all message body content in a parameters element as shown in the example below. Include each parameter in a separate child element. Use the name of the parameter as its element name. For positional parameters that do not have names, use the arg1, arg2, arg3 convention to name their elements. See Positional Parameters (page 115).
<parameters> <arg1>MyUsername</arg1> <arg2>MyPassword</arg2> <atg-rest-user-input>MyMessageId</atg-rest-user-input> </parameters>
Make sure that you specify Content-Type: application/xml in the HTTP message. See Setting the ContentType Value (page 117).
117
JSON Parameter Markup

You can use JavaScript Object Notation (JSON) to format parameters in the message body of an Oracle ATG Web Commerce platform REST Web Services request. Enclose the parameters in standard JSON format as shown in the example below. Include each parameter in a separate name and value pair. Use the name of the parameter as the name for the pair. For positional parameters that do not have names, use the arg1, arg2, arg3 convention as the names for the pairs. See Positional Parameters (page 115).
{ "arg1": "MyUsername", "arg2": "MyPassword", "atg-rest-user-input": "MyMessageId" }
Make sure that you specify Content-Type: application/json in the HTTP message. See Setting the Content-Type Value (page 117). The following example shows numeric parameter input using JSON markup.
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/json" -d "{ "arg1" : 4 }" \ http://myserver:8080/rest/bean/atg/rest/Configuration/maxDepthAllowed
URL Query String Parameter Markup

You can use the URL query string format to include parameters in the message body of an Oracle ATG Web Commerce platform REST Web Services request. Include the parameters in standard URL query string format as shown in the example below. Include each parameter in a separate name and value pair. Use the name of the parameter as the name for the pair. For positional parameters that do not have names, use the arg1, arg2, arg3 convention as the names for the pairs. See Positional Parameters (page 115).
arg1=MyUsername&arg2=MyPassword&atg-rest-user-input=MyMessageId
URL encode any special URL characters in the parameter values. Make sure that you specify Content-Type: application/x-www-form-urlencoded in the HTTP message. See Setting the Content-Type Value (page 117).
Input Values
This section provides information about the way the Oracle ATG Web Commerce platform REST Web Services server expects to receive parameter values.
118
Primitive Values in Input

Format primitive values as shown in the following table.
Value Type String Number Boolean
Values Accepted A sequence of characters. For example, MyUsername. An integer or decimal number. For example, 123 or 123.456.
true and false
See more information about setting property values in Setting Component Properties (page 140) and Setting Repository Item Properties (page 162).
Multiple Values in Input

The REST Web Services server will accept map and collection input when you set the values of properties that accept multiple values. Unless you are setting the value of a repository item, you must specify the Java classes used for the container and the contents. When you set the value of a non-repository, Nucleus component property, the REST Web Services server will replace all values with any new values that you set. To append a value to an existing collection, you must supply all the existing values along with the new values. You can configure the way the REST Web Services server appends or replaces multiple values in a repository item property. See Appending Values to Repository Item Properties (page 120) and Replacing Multiple Values in a Repository Item Property (page 121). The following example shows a REST Web Services request that appends a value to a non-repository component property. It includes all existing values in the property along with the new value. To remove a value, make a similar request that includes only the values that you wish to remain in the property.
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/json" \ -d "{'atg-rest-param-class-types':{'container-class':'java.util.ArrayList','elementclass':'java.lang.String'},'arg1':['Existing String in the Collection','New String for the Collection']}" \ http://myserver:7003/rest/bean/atg/MyDog/tricks?atg-rest-json-input=true
See more information about setting property values in Setting Component Properties (page 140) and Setting Repository Item Properties (page 162).
Specifying Java Classes for Multiple Value Input

Specify the Java classes for your array, collection, and map values as shown in the following table.
119
Value Type Array
Format <array-element-class>:[value1,value2,...,valueN] For example:

java.lang.String:[foo,bar,baz]
Collection
<collection-container-class>:<element-class>:[value1,value2,...,valueN] For example:

java.util.ArrayList:java.lang.String:[foo,bar,baz]
Map
<map-class>:<key-class>:<value-class>:[key1=value1,key2=value2,key3=value3] For example:

java.util.HashMap:java.lang.String:java.lang.String: [foo=soccer,bar=baseball,baz=football]
If your input is in JSON format, you can use the atg-rest-param-class-types control parameter to specify Java classes. The atg-rest-param-class-types parameter includes two components, container-class and element-class. Include this attribute in your JSON input as shown below.
{'atg-rest-param-class-types':{'container-class':'java.util.ArrayList','elementclass':'java.lang.String'},'arg1':['sit','stay','speak']}
See information about the atg-rest-param-class-types parameter in the Control Parameter Reference (page 113).
Appending Values to Repository Item Properties

To append data to a repository item property that holds multiple values, set the new value as you would for a single value property. See Setting Repository Item Properties (page 162). The following example adds two repository item reference values to a repository item property that can hold multiple values. Any existing values in that property will remain there.
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>/atg/commerce/gifts/Giftlists/gift-list/gl40050,/atg/commerce/ gifts/Giftlists/gift-list/gl40052</arg1></parameters>" \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/ user/130001/giftlists
Note: The REST Web Services server is configured to append values to repository item properties that accept multiple values by default. The appendMultiValuesByDefault configuration property controls this behavior for repository item properties. If you have reconfigured this setting, set the atg-rest-append-multivalues control parameter to true for each REST Web Services request that should append the new value. See appendMultiValuesByDefault (page 178).
120
Replacing Multiple Values in a Repository Item Property

To replace all the existing values in a repository item property that holds multiple values, include the atg-restappend-multi-values control parameter with your REST Web Services request. Set the value of the control parameter to false. Note: You can only use the rest-append-multi-values control parameter with repository item properties. It does not affect the way you can update non-repository properties. The following example replaces all the values that are currently in a repository item property that holds multiple values. Only the repository item reference that is in the functional parameter will remain in the property.
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>/atg/commerce/gifts/Giftlists/gift-list/gl40049</arg1></ parameters>" \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/ user/130001/giftlists?atg-rest-append-multi-values=false
JSON Markup Input for Multiple Value Repository Item Properties

If you are setting multiple values in a repository item property, you can use standard JSON markup for the collection or map value. Include the atg-rest-json-input with your REST Web Service request and set its value to true. You can include JSON markup for multiple values in any input format. The following example shows a REST Web Services request that includes a JSON collection in an XML message body parameter.
curl.exe -v -b cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>[ "/atg/commerce/gifts/Giftlists/gift-list/gl40050", "/atg/ commerce/gifts/Giftlists/gift-list/gl40052" ]</arg1></parameters>" \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/ user/130001/giftlists?atg-rest-json-input=true
Object Values in Input

To set a property that takes a Java object as its value, include the atg-rest-class-type control parameter along with the initial properties for the object in the positional parameter for the property value. The atgrest-class-type control parameter specifies the Java class of the object. Use either JSON or XML to enclose the positional parameter. The REST Web Services server will return a boolean value to indicate whether the object property has been set successfully. If it is set successfully, the returned value is true. See more information about setting property values in Setting Component Properties (page 140) and Setting Repository Item Properties (page 162). Note: The REST Web Services interface can only create objects of classes that have a nullary constructor. At least one constructor for the class must have no arguments. Here is an object property value encoded in JSON. The class for the object is atg.MyObjectValue. The following parameters set properties of the new object.
121
{"arg1": {"atg-rest-class-type" : "atg.MyObjectValue", "name" : "Berthoud", "height" : "1"} }
Here is the same object property value, encoded in XML.
<parameters> <arg1> <atg-rest-class-type>atg.MyObjectValue</atg-rest-class-type> <name>Berthoud</name> <height>1</height> </arg1> </parameters>
The following example shows a POST request to set an object property value for a Nucleus component.
$ curl -v -b cookies.txt -X POST -H "Content-Type: application/json" -d "{"arg1": {"atg-rest-class-type":"atg.MyObjectValue","name":"Berthoud","height":"1"}}" http:// myserver:7003/rest/bean/atg/MyDog/objectvalue * About to connect() to myserver port 7003 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 7003 (#0) > POST /rest/bean/atg/MyDog/objectvalue HTTP/1.1 > User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5 > Host: myserver:7003 > Accept: */* > Cookie: JSESSIONID=llf3PN8N0CfQ6h41Y278NfLjvCJZn6CR8ydhQRbg7GTQ7Nn5mW8p!1359398113; DYN_USER_CONFIRM=838bac4608584930cf177410e3b46448; DYN_USER_ID=110001 > Content-Type: application/json > Content-Length: 69 > < HTTP/1.1 200 OK < Date: Wed, 29 Feb 2012 05:52:39 GMT < Transfer-Encoding: chunked < Content-Type: application/json; charset=UTF-8 < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMSxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjE= < X-Powered-By: Servlet/2.5 JSP/2.1 < * Connection #0 to host myserver left intact * Closing connection #0 {"atgResponse": true}
Nested Multiple Value Objects in Input

To set a property value that takes a Java object that holds other Java objects, use the atg-rest-classdescriptor control parameter to specify the Java class of the nested objects. For example, if you are setting a property value that takes a List of Sets, indicate the Java class of the Set using the atg-rest-classdescriptor parameter. Then include the values for the nested Sets.
122
The name of the parameter inside the atg-rest-class-descriptor matches the name of one of the actual values that you supply later in the input parameter. The input structure for nested multiple value objects builds on the structure for input objects in general. See Object Values in Input (page 121). The following example uses the atg-rest-class-descriptor control parameter to specify that the value of the myListOfSets property is a java.util.ArrayList object. That ArrayList object holds java.util.HashSet objects. After the atg-rest-class-descriptor, the example provides the values that are nested inside the myListOfSets property.
{arg1 : { "atg-rest-class-type":"foo.class.WithNestedMultis", "atg-rest-class-descriptor": { "myListOfSets": { "container-class": "java.util.ArrayList", "element-class": "java.util.HashSet" } }, "myListOfSets": [["red","blue"],["green","yellow"]] } }
Here is the same object property value, encoded in XML.
<arg1> <atg-rest-class-type>foo.class.WithNestedMultis</atg-rest-class-type> <atg-rest-class-descriptor> <myListOfSets> <container-class>java.util.ArrayList</container-class> <element-class>java.util.HashSet</element-class> </myListOfSets> </atg-rest-class-descriptor> <myListOfSets> <element> <element>red</element> <element>blue</element> </element> <element> <element>green</element> <element>yellow</element> </element> </myListOfSets> </arg1>
Three or More Nested Levels

Include additional container-class and element-class parameters for each nested level of multiple value objects. The element-class parameter of the parent object holds the additional container-class and element-class parameters. For example:
"atg-rest-class-descriptor": {
123
"myListOfSets": { "container-class": "java.util.ArrayList", "element-class": { "container-class": "java.util.HashSet", "element-class": "java.util.HashMap" } } }
Array Types
To specify an array type in the atg-rest-class-descriptor control parameter, use the standard Java notation for arrays.
Array Type String byte int Two-dimensional array of Strings
Java Notation
[Ljava.lang.String; [B [I [[Ljava.lang.String;
Key Class Types for Map Values

Keys for Map object values must be Strings. No other class types are supported.
Date Format in Input

Use the following date format when sending dates to the REST Web Services interface.
MM/dd/yyyy HH:mm:ss z
For example, 01/29/2015 14:45:11 PDT
Setting Properties to Null

Use the atg-rest-null parameter to set the value of a component or repository item property to null. Set the property and include this parameter as the new value. The following example sets the value of a component property to null. See more information about setting property values in Setting Component Properties (page 140) and Setting Repository Item Properties (page 162).
$ curl -v -b cookies.txt -X POST \
124
-H "Content-Type: application/json" \ -d "{"arg1":"atg-rest-null"}" \ http://myserver:7003/rest/bean/atg/MyDog/name * About to connect() to myserver port 7003 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 7003 (#0) > POST /rest/bean/atg/MyDog/name HTTP/1.1 > User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5 > Host: myserver:7003 > Accept: */* > Cookie: JSESSIONID=S31vPTNFpLQQ7Bj6l16wh5KgDqqv18yXxwy1khgBpvqRkW5NfQRm!1359398113; DYN_USER_CONFIRM=838bac4608584930c f177410e3b46448; DYN_USER_ID=110001 > Content-Type: application/json > Content-Length: 20 > < HTTP/1.1 200 OK < Date: Thu, 01 Mar 2012 01:18:50 GMT < Transfer-Encoding: chunked < Content-Type: application/json; charset=UTF-8 < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMSxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjE= < X-Powered-By: Servlet/2.5 JSP/2.1 < * Connection #0 to host myserver left intact * Closing connection #0 {"atgResponse": true}
HTTP Status Codes

The Oracle ATG Web Commerce platform REST Web Services server returns an HTTP status code to indicate the result of each request. The HTTP status codes that it returns are: 200 (OK) - The request was processed successfully. This does not mean that it had the result you intended. See information about how to determine success or failure in the instructions for specific operations. 201 (Created) - Returned only for POST requests that create repository items. The request was successful and the repository item was created. 400 (Bad Request) - The request could not be completed because the request URL and/or parameters were improperly formatted. 401 (Unauthorized) - The user session does not have the proper security credentials to execute the method, property, or access the repository for the requested resource. 403 (Forbidden) The specified property has been configured as not writable via the filtering configuration. 404 (Not Found) - The request could not be completed because it was made for a resource that does not exist. 410 (Gone) - Returned only for DELETE requests that remove repository items. The request was successful and the repository item was deleted. 500 (Internal server error) - The request could not be completed because an unexpected exception occurred.
125
Returned Data
The Oracle ATG Web Commerce platform REST Web Services server will return the results of the operations you perform in an HTTP response message body. The contents of the returned data depend on the operation you are performing. This section explains the formats that the server will return data in. It also explains how to configure the server to return data in the manner you choose.
Choosing Output Markup

The Oracle ATG Web Commerce platform REST Web Services server can return output data in either JavaScript Object Notation (JSON) or eXtensible Markup Language (XML) format. It will enclose all returned data in a JSON object with the name atgResponse or an atgResponse XML element. The following example shows JSON output markup.
{"atgResponse": "280001"}
The following example shows XML output markup.

<atgResponse>280001</atgResponse>
Default Output Markup

Configure your Oracle ATG Web Commerce platform REST Web Server to return output data in the format you choose. The default output format of the server is controlled by its /atg/rest/Configuration/ defaultOutputCustomizer property. For JSON output, set the property to /atg/rest/output/JSONOutputCustomizer. For XML output, set the property to /atg/rest/output/XMLOutputCustomizer. The server will return data in its default output format if you do not specify the output format for an individual request. See Specifying Output Markup for One Request (page 126).
Specifying Output Markup for One Request

You can choose either JSON or XML for the returned data of a single Oracle ATG Web Commerce platform REST Web Services request. The output format you specify for an individual request will override the default output markup setting. To specify the output format for an individual REST Web Services request, include the atg-rest-output control parameter with that request. Set the value of atg-rest-output to either json or xml. See Control Parameters (page 112). The following example shows a REST Web Services request that includes the atg-rest-output control parameter. The control parameter specifies that data should be returned using XML markup.
curl -v -b cookies.txt -X GET \ http://servername:port/rest/bean/atg/dynamo/Configuration?atg-rest-output=xml
126
JSON Output
The following example shows JSON output. Notice how string values are surrounded by quotes, numerical values have no quotes, multivalve elements are surrounded by brackets, and references to repository items are URLs to the item referenced. Note that multivalve elements will be URLs also, but in this example, the abcArray has been expanded.
{ "myClass": "class atg.rest.processor.MockObject", "size": 10, "abcArray": { "type": "int", "elements": [ 0, 1, 2, 3 ] }, "product": "http://localhost/rest/repository/atg/commerce/catalog/ProductCatalog/ product/prod12345" }
XML Output
The following example shows XML output.
<atgResponse> <organizationPathCache> <atgRestComponentPath>/atg/userprofiling/OrganizationPathCache</ atgRestComponentPath> </organizationPathCache> <rootOrganizationPrimaryKey>root</rootOrganizationPrimaryKey> [Additional property values omitted to save space] <roles> <element> -- RepositoryItemGroupRole: --> name: Young --> primary key: Young__grouprole </element> <element> -- RepositoryItemGroupRole: --> name: WomenOnly --> primary key: WomenOnly__grouprole </element> <element> -- RepositoryItemGroupRole: --> name: Fashionista --> primary key: Fashionista__grouprole </element> <element> -- RepositoryItemGroupRole: --> name: MenOnly
127
--> primary key: MenOnly__grouprole </element> <element> -- RepositoryItemGroupRole: --> name: ThirtySomethings --> primary key: ThirtySomethings__grouprole </element> </roles> [Additional property values omitted to save space] </atgResponse>
Identifying a Response
You can include an identifying string with an Oracle ATG Web Commerce platform REST Web Services request and the server will include that string in the response it returns. One use of this function is to identify the response to an asynchronous REST Web Service request. To specify the identifying string for a REST Web Services response, include the atg-rest-user-input control parameter in your HTTP request. Set the value of the control parameter to the identifying string. See Control Parameters (page 112). The following example shows a REST Web Services request that includes the atg-rest-user-input control parameter.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/bean/atg/dynamo/Configuration/httpPort?atg-rest-userinput=MyMessageId001 * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > GET /rest/bean/atg/dynamo/Configuration/httpPort?atg-rest-user-input=MyMessageId001 HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: JSESSIONID=AD84270CB05CC0960580D1B875595822 > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc 2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ== < Content-Type: application/json;charset=UTF-8 < Transfer-Encoding: chunked < Date: Fri, 22 Oct 2010 16:36:07 GMT < { "atg-rest-response": {"httpPort": 8080}, "atg-rest-user-input": "MyMessageId001" }* Connection #0 to host myserver left intact * Closing connection #0
128
Multiple Values in Output

This section provides information about the format of collection and map values in response messages from the REST Web Services server.
Expanding Multiple Values and Complex Objects

The REST Web Services server returns multiple-values and complex objects as REST paths by default. Include the atg-rest-show-rest-paths control parameter to expand these values in the response you receive. Set the value of the control parameter to true. If you set atg-rest-show-rest-paths to false, the REST response will include expanded data for nested properties down to the level specified by the atg-rest-depth control parameter. See Return Depth (page 134). You can configure the default setting for atg-rest-show-rest-paths. See showRestPaths for JSON (page 175) and showRestPaths for XML (page 177). The example below shows a REST path in the creditCards property. The example that follows it shows the effect of the atg-rest-show-rest-paths control parameter.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/ user/130001/ * * * > > > > > > < < < * About to connect() to myserver port 8080 (#0) Trying 12.34.567.890... connected Connected to myserver (12.34.567.890) port 8080 (#0) GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/ HTTP/1.1 User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 Host: myserver:8080 Accept: */* Cookie: DYN_USER_ID=140003; JSESSIONID=9B95CAFAA8B94A05C46488E482A91543; DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b
HTTP/1.1 200 OK Server: Apache-Coyote/1.1 X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 Replaced cookie JSESSIONID="A2C79A00F7194A1F113604FD1C4BE7DD" for domain myserver, path /, expire 0 < Set-Cookie: JSESSIONID=A2C79A00F7194A1F113604FD1C4BE7DD; Path=/ < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2 Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Fri, 05 Nov 2010 21:50:44 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> [Additional property values omitted to save space] <creditCards>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/user/130001/creditCards</creditCards> [Additional property values omitted to save space]
129
</atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
The example below shows a collection value that has been expanded. The REST Web Services request sets the atg-rest-show-rest-paths control parameter to false.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/ user/130001/?atg-rest-show-rest-paths=false * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/?atgrest-show-rest-paths=false HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: DYN_USER_ID=140003; JSESSIONID=9B95CAFAA8B94A05C46488E482A91543; DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 * Replaced cookie JSESSIONID="9D730DE9D4A7C250994F20363ACC3FA6" for domain myserver, path /, expire 0 < Set-Cookie: JSESSIONID=9D730DE9D4A7C250994F20363ACC3FA6; Path=/ < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybU xpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Fri, 05 Nov 2010 22:04:32 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> [Additional property values omitted to save space] <creditCards> <element> <key>MyOtherCard</key> <value> <atgRestComponentPath>/atg/userprofiling/ProfileAdapterRepository</ atgRestComponentPath> <atgRestItemDescriptor>credit-card</atgRestItemDescriptor> <atgRestRepositoryId>usercc10003</atgRestRepositoryId> </value> </element> <element> <key>MyCard</key> <value> <atgRestComponentPath>/atg/userprofiling/ProfileAdapterRepository</ atgRestComponentPath> <atgRestItemDescriptor>credit-card</atgRestItemDescriptor> <atgRestRepositoryId>usercc10001</atgRestRepositoryId>
130
</value> </element> </creditCards> [Additional property values omitted to save space] </atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
Collection Values in Output

The REST Web Services server will return each element in a property value of class java.utils.Collection as shown in the examples below.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/bean/atg/userprofiling/ProfileUserDirectory/roles * * * > > > > > > < < < * * < < About to connect() to myserver port 8080 (#0) Trying 12.34.567.890... connected Connected to myserver (12.34.567.890) port 8080 (#0) GET /rest/bean/atg/userprofiling/ProfileUserDirectory/roles HTTP/1.1 User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 Host: myserver:8080 Accept: */* Cookie: DYN_USER_ID=140003; JSESSIONID=9B95CAFAA8B94A05C46488E482A91543; DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b
HTTP/1.1 200 OK Server: Apache-Coyote/1.1 X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 Replaced cookie JSESSIONID="6F710DD421CDBB1C0A092133210E7A0E" for domain myserver, path /, expire 0 Set-Cookie: JSESSIONID=6F710DD421CDBB1C0A092133210E7A0E; Path=/ X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9yb UxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Wed, 03 Nov 2010 15:05:19 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <roles> <element> -- RepositoryItemGroupRole: --> name: Young --> primary key: Young__grouprole </element> <element> -- RepositoryItemGroupRole: --> name: WomenOnly --> primary key: WomenOnly__grouprole </element> <element> -- RepositoryItemGroupRole: --> name: Fashionista --> primary key: Fashionista__grouprole </element> <element>
131
-- RepositoryItemGroupRole: --> name: MenOnly --> primary key: MenOnly__grouprole </element> <element> -- RepositoryItemGroupRole: --> name: ThirtySomethings --> primary key: ThirtySomethings__grouprole </element> </roles></atgResponse>* Connection #0 to host myserver left intact * Closing connection #0
The following example shows the same property value in JSON format.
{"roles": [ "\n-- RepositoryItemGroupRole:\n--> \n", "\n-- RepositoryItemGroupRole:\n--> WomenOnly__grouprole\n", "\n-- RepositoryItemGroupRole:\n--> Fashionista__grouprole\n", "\n-- RepositoryItemGroupRole:\n--> MenOnly__grouprole\n", "\n-- RepositoryItemGroupRole:\n--> ThirtySomethings__grouprole\n" ]}
name: Young\n--> primary key: Young__grouprole name: WomenOnly\n--> primary key: name: Fashionista\n--> primary key: name: MenOnly\n--> primary key: name: ThirtySomethings\n--> primary key:
Map Values in Output

The REST Web Services server will return each element in a property value of class java.utils.Map as shown in the examples below.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/ user/130001/creditCards * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/ creditCards HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: DYN_USER_ID=140003; JSESSIONID=9B95CAFAA8B94A05C46488E482A91543; DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 * Replaced cookie JSESSIONID="F60503E5A6051C18D119B6CE470F9591" for domain myserver, path /, expire 0 < Set-Cookie: JSESSIONID=F60503E5A6051C18D119B6CE470F9591; Path=/ < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2V uc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Wed, 03 Nov 2010 16:12:57 GMT
132
< <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <creditCards> <element> <key>MyOtherCard</key> <value>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/credit-card/usercc10003</value> </element> <element> <key>MyCard</key> <value>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/credit-card/usercc10001</value> </element> </creditCards> </atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
{"creditCards": { "MyCard": "http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/credit-card/usercc10001", "MyOtherCard": "http:// myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/credit-card/ usercc10003" }}
Array Values in Output

The REST Web Services server will return each element in a property value that is an array as shown in the examples below.
curl -v -b cookies.txt -X GET http://12.34.567.890:7003/rest/repository/atg/ userprofiling/ProfileAdapterRepository/us er/190000/previousPasswords * About to connect() to 12.34.567.890 port 7003 (#0) * Trying 12.34.567.890... connected * Connected to 12.34.567.890 (12.34.567.890) port 7003 (#0) > GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/190000/ previousPasswords HTTP/1.1 > User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5 > Host: 12.34.567.890:7003 > Accept: */* > Cookie: DYN_USER_CONFIRM=4587a098fc47b063d7e60c9097fa3c99; DYN_USER_ID=140001; JSESSIONID=PGpxTW0BWgSfQT2sXspwJf3H3JJK dTGHgJ1yMZ1QV8V1GRQJ9MVN!-249339435 > < HTTP/1.1 200 OK < Date: Thu, 13 Oct 2011 16:18:22 GMT < Transfer-Encoding: chunked < Content-Type: application/xml; charset=UTF-8 < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMSxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjE= * Replaced cookie JSESSIONID="V9TCTXPTkCnXrgJJKb2bhbzHwpvn2yzlDJb4JTXhLlkyw22J7xm7!-249339435" for domain 12.34.567.890, path /, expire 0
133
< Set-Cookie: JSESSIONID=V9TCTXPTkCnXrgJJKb2bhbzHwpvn2yzlDJb4JTXhLlkyw22J7xm7!-249339435; path=/; HttpOnly < X-Powered-By: Servlet/2.5 JSP/2.1 < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <previousPasswords> <element>17d0b74864b89840e07f08f46dd72f90fed59b62d476639c25667a3b3f74bdf5</element> <element>914eb28cb2996739bdd33ed74deed1005ff1fd40489583d22bd35d5a8344fa6c</element> </previousPasswords> </atgResponse> * Connection #0 to host 12.34.567.890 left intact * Closing connection #0
{"previousPasswords": [ "17d0b74864b89840e07f08f46dd72f90fed59b62d476639c25667a3b3f74bdf5", "914eb28cb2996739bdd33ed74deed1005ff1fd40489583d22bd35d5a8344fa6c" ]}
Return Depth
You can control the number of nested levels of property information that the REST Web Services server will return when you request property values. Use the atg-rest-depth control parameter to specify the number of levels that will be included in returned data. The number of nested levels you can expand in returned data is limited by the maxDepthAllowed configuration for the REST Web Services server. See maxDepthAllowed (page 173). The default number of levels is zero which returns only the immediate properties of the Nucleus component you specify in your request. If one of those properties includes multiple values or is a complex object, the returned data will include only the REST path of the property value. For example:
<creditCards>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/user/130001/creditCards</creditCards>
If you set the return depth to one, the returned data will expand properties that contain multiple values and complex objects. The individual values within them will be included in the returned data. For example:
<creditCards> <element> <key>MyOtherCard</key> <value> <atgRestComponentPath>/atg/userprofiling/ProfileAdapterRepository</ atgRestComponentPath> <atgRestItemDescriptor>credit-card</atgRestItemDescriptor> <atgRestRepositoryId>usercc10003</atgRestRepositoryId> </value> </element> <element>
134
<key>MyCard</key> <value> <atgRestComponentPath>/atg/userprofiling/ProfileAdapterRepository</ atgRestComponentPath> <atgRestItemDescriptor>credit-card</atgRestItemDescriptor> <atgRestRepositoryId>usercc10001</atgRestRepositoryId> </value> </element> </creditCards>
Date Format in Returned Data

You can configure the format for dates that are returned by the REST Web Services interface. It will return dates in one of the following formats: A string representation of a Java Date object (default) MM/dd/yyyy HH:mm:ss z For example: 01/29/2011 11:11:11 GMT To control which date format will be returned, set the enableFormatDateOutput property of the /atg/rest/ output/JSONOutputCustomizer or /atg/rest/output/XMLOutputCustomizer components. Set enableFormatDateOutput to true to receive the date and time in MM/dd/yyyy HH:mm:ss z format. Set enableFormatDateOutput to false to receive the string representation of the Date object. Note: The return depth for a REST request may cause a date property to be expanded. If a date property is expanded, it will not be in either of the formats described in this section but will be a set of properties that make up the date. See Return Depth (page 134). If you do not want to expand date properties, you can suppress property expansion for them. See Suppressing Property Expansion (page 171).
Time Zone Configuration

If you set the enableFormatDate property of the JSONOutputCustomizer or XMLOutputCustomizer to true, the REST Web Services interface returns date values using the time zone specified by the timeZoneId property. The default value for this property is Coordinated Universal Time (UTC). Set the timeZoneId property of JSONOutputCustomizer or XMLOutputCustomizer to the time zone identifier that you choose. Specify the time zone using a string recognized by the java.util.TimeZone class. If you choose to return the string representation of Java Date objects, the REST interface will return date values using the time zone of the server.
Errors and Exceptions

If an error or exception occurs when you use the Oracle ATG Web Commerce platform REST Web Services, the server will indicate the nature of the problem in the HTTP response status code. See HTTP Status Codes (page 125).
135
Problems Performing Operations

If the REST Web Services server can process the input in your request but it encounters problems performing an operation it will return HTTP status code 400 Bad Request. The following example shows an exception that has been returned by the REST Web Services server. HTTP status code 400 Bad Request indicates that the server cannot perform the requested action because of a problem with the input provided. The server includes the name of the exception (atg.beans.PropertyNotFoundException) in the message body of the response.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/bean/atg/dynamo/Configuration/fakeProperty * * * > > > > > > < < < < About to connect() to myserver port 8080 (#0) Trying 12.34.567.890... connected Connected to myserver (12.34.567.890) port 8080 (#0) GET /rest/bean/atg/dynamo/Configuration/fakeProperty HTTP/1.1 User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 Host: myserver:8080 Accept: */* Cookie: JSESSIONID=67B1EAF58CC556CE7C628CDE6F395FB4
HTTP/1.1 400 Bad Request Server: Apache-Coyote/1.1 X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxp Y2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ== < Content-Type: text/html;charset=utf-8 < Content-Length: 1585 < Date: Fri, 22 Oct 2010 19:48:53 GMT < Connection: close < <html><head><title>JBoss Web/2.1.3 - Error report</title><style></style> </head><body><h1>HTTP Status 400 atg.beans.PropertyNotFoundException: Can't find property named: fakeProperty in class: atg.service.dynamo.DAFConfiguration Can't find property named: fakeProperty in class: atg.service.dynamo.DAFConfiguration</h1><HR size="1" noshade="noshade"><p><b>type</ b> Status report</p><p><b>message</b> <u>atg.beans.PropertyNotFoundException: Can't find property named: fakeProperty in class: atg.service.dynamo.DAFConfiguration Can't find property named: fakeProperty in class: atg.service.dynamo.DAFConfiguration</ u></p><p><b>description</b> <u>The request sent by the client was syntactically incorrect (atg.beans.PropertyNotFoundException: Can't find property named: fakeProperty in class: atg.service.dynamo.DAFConfiguration Can't find property named: fakeProperty in class: atg.service.dynamo.DAFConfiguration).</u></p><HR size="1" noshade="noshade"><h3>JBoss Web/2.1.3</h3> </body></html>* Closing connection #0
136
Problems Processing a Request

If the REST Web Services server cannot process the input in your request it will return HTTP status code 500 Internal Server Error. The following example shows an exception that has been returned by the REST Web Services server. HTTP status code 500 Internal Server Error indicates that the server cannot process the request because of a problem interpreting the input. The server includes the name of the exception (org.dom4j.DocumentException) in the message body of the response.
curl -v -c cookies.txt -X POST \ -H "Content-Type: application/xml" -d "This is not XML." \ http://myserver:8080/rest/bean/atg/userprofiling/ProfileServices/loginUser * * * > > > > > > > < < < * About to connect() to myserver port 8080 (#0) Trying 12.34.567.890... connected Connected to myserver (12.34.567.890) port 8080 (#0) POST /rest/bean/atg/userprofiling/ProfileServices/loginUser HTTP/1.1 User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 Host: myserver:8080 Accept: */* Content-Type: application/xml Content-Length: 16
HTTP/1.1 500 Internal Server Error Server: Apache-Coyote/1.1 X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 Added cookie JSESSIONID="24C3CC9056EA3A1B62DD2002DEDFAA7F" for domain myserver, path /, expire 0 < Set-Cookie: JSESSIONID=24C3CC9056EA3A1B62DD2002DEDFAA7F; Path=/ < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2U vMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: text/html;charset=utf-8 < Content-Length: 1776 < Date: Wed, 27 Oct 2010 18:15:29 GMT < Connection: close < <html><head><title>JBoss Web/2.1.3 - Error report</title><style></style> </head><body><h1>HTTP Status 500 org.dom4j.DocumentException: Error on line 1 of document : Content is not allowed in prolog. Nested exception: Content is not allowed in prolog. Error on line 1 of document : Content is not allowed in prolog. Nested exception: Content is not allowed in prolog.</h1><HR size="1" noshade="noshade"><p><b>type</b> Status report</ p><p><b>message</b> <u>org.dom4j.DocumentException: Error on line 1 of document : Content is not allowed in prolog. Nested exception: Content is not allowed in prolog. Error on line 1 of document : Content is not allowed in prolog. Nested exception: Content is not allowed in prolog.</u></p><p><b>description</b> <u>The server encountered an internal error (org.dom4j.DocumentException: Error on line 1 of document : Content is not allowed in prolog. Nested exception: Content is not allowed in prolog. Error on line 1 of document : Content is not allowed in prolog. Nested exception: Content is not allowed in prolog.) that prevented it from fulfilling this
137
request.</u></p><HR size="1" noshade="noshade"><h3>JBoss Web/2.1.3</h3></body></html>* Closing connection #0
138
11 Working with Component Properties
This section provides instructions for Oracle ATG Web Commerce platform REST Web Services operations involving Nucleus component properties.
Getting Component Properties

To get the value of a Nucleus component property, send a REST Web Services request as described in the following table.
Request Component HTTP Method Functional Parameters URL
Value GET None Include the component pathname in the application path after /rest/ bean/. Include the name of the property at the end of the path. See Nucleus Components (page 105). To get the values of all properties of a component, do not include a property name at the end of the path.
The following example shows a REST Web Services request that returns the value of the atg/dynamo/ Configuration.httpPort property.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/bean/atg/dynamo/Configuration/httpPort * * * > > About to connect() to myserver port 8080 (#0) Trying 12.34.567.890... connected Connected to myserver (12.34.567.890) port 8080 (#0) GET /rest/bean/atg/dynamo/Configuration/httpPort HTTP/1.1 User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5
139
> > > > < < < <
Host: myserver:8080 Accept: */* Cookie: JSESSIONID=8DC60C0801D934F472BD9BE8A15A54F9
HTTP/1.1 200 OK Server: Apache-Coyote/1.1 X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxp Y2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ== < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Mon, 25 Oct 2010 21:29:05 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <httpPort>8080</httpPort> </atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
The following example shows a REST Web Services request that returns all the properties of a Nucleus component.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/bean/atg/dynamo/Configuration
Setting Component Properties

To set the value of a Nucleus component property, send a REST Web Services request as described in the following table.
Request Component HTTP Method Functional Parameters
Value POST or PUT Include the new value for the property. Use the positional parameter name arg1 for the value. See Positional Parameters (page 115).
URL
Include the component pathname in the application path after /rest/ bean/. Include the name of the property at the end of the path. See Nucleus Components (page 105).
The following example shows a REST Web Services request that sets the value of the atg/userprofiling/ passwordchecker/PasswordRuleChecker.enabled property.
140
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>false</arg1></parameters>" \ http://myserver:8080/rest/bean/atg/userprofiling/passwordchecker/PasswordRuleChecker/ enabled * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > POST /rest/bean/atg/userprofiling/passwordchecker/PasswordRuleChecker/enabled HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: JSESSIONID=7205768051AC55AAFD5020D8931C71A7 > Content-Type: application/xml > Content-Length: 43 > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxp Y2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ== < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Tue, 26 Oct 2010 14:58:28 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse>true</atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
141
142
12 Invoking Component Methods
To invoke a Nucleus component method, send a REST Web Services request as described in the following table.
Value POST Include any arguments to the method as positional parameters. The name of the parameter for the first argument is arg1. The name of the parameter for the second argument is arg2. Continue this naming pattern for any further arguments. See Positional Parameters (page 115). Include the component pathname in the application path after /rest/ bean/. Include the name of the method at the end of the path. See Nucleus Components (page 105).
URL
The following example shows a REST Web Services request that invokes the /atg/commerce/order/ OrderManager.getOrderCountForProfile method. The method takes a user identifier as its argument and it returns an integer value.
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>130001</arg1></parameters>" \ http://myserver:8080/rest/bean/atg/commerce/order/OrderManager/getOrderCountForProfile * * * > > > > > About to connect() to myserver port 8080 (#0) Trying 12.34.567.890... connected Connected to myserver (12.34.567.890) port 8080 (#0) POST /rest/bean/atg/commerce/order/OrderManager/getOrderCountForProfile HTTP/1.1 User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 Host: myserver:8080 Accept: */* Cookie: DYN_USER_ID=120001; JSESSIONID=7C4C04BFDA404FA7D9443A820F32BE0D; DYN_USER_CONFIRM=bca3eb6c2cdeb0e4a625c7165a088e2e > Content-Type: application/xml > Content-Length: 44 > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
143
< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2Uv MCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Wed, 27 Oct 2010 17:17:33 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse>2</atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
144
13 Invoking Form Handlers
To invoke a Nucleus form handler, send a REST Web Services request as described in the following table.
Value POST Submit the required property values of the form as functional parameters. Name each parameter with the property name it corresponds to. See Submitting Form Values (page 146). Include the component pathname in the application path after /rest/bean/. Include the name of the form handler operation at the end of the path. See Nucleus Components (page 105).
URL
The following example shows a REST Web Services request that invokes the create operation of /atg/store/ profile/RegistrationFormHandler. The HTTP request includes functional parameters to supply the value property of the form handler. The data type of the value property is java.util.Dictionary; parameter names such as value.password correspond to the password key in the dictionary value.
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/json" \ -d "{ "value.email":"sheroux@example.com", "value.password":"mypassword", "value.confirmPassword":"mypassword", "value.firstName":"Severe", "value.lastName":"Heroux" }" \ http://myserver:8080/rest/bean/atg/store/profile/RegistrationFormHandler/create * * * > > > > > About to connect() to myserver port 8080 (#0) Trying 12.34.567.890... connected Connected to myserver (12.34.567.890) port 8080 (#0) POST /rest/bean/atg/store/profile/RegistrationFormHandler/create HTTP/1.1 User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 Host: myserver:8080 Accept: */* Cookie: DYN_USER_ID=140003; JSESSIONID=1DEDBDEE3BF322FA71AFE89438DCCF9E; DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b > Content-Type: application/json > Content-Length: 147 > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1
145
< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2 Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= * Replaced cookie DYN_USER_ID="140003" for domain myserver, path /, expire 1291317542 < Set-Cookie: DYN_USER_ID=140003; Expires=Thu, 02-Dec-2010 19:19:02 GMT; Path=/ * Replaced cookie DYN_USER_CONFIRM="1231cf3e7573bf936dbd29dbbbfe150b" for domain myserver, path /, expire 1291317542 < Set-Cookie: DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b; Expires=Thu, 02Dec-2010 19:19:02 GMT; Path=/ < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Tue, 02 Nov 2010 19:19:02 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse>true</atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
Submitting Form Values

When you invoke a form handler, you must present it with a set of values as functional parameters. These values are the data that would be submitted in form fields if the form handler were being invoked from a user interface. Different types of form handlers require different parameters depending on the function they perform. See more information about form handlers in the ATG Page Developer's Guide. For example, the /atg/store/profile/RegistrationFormHandler form handler requires a java.util.Dictionary property named value that holds a set of dictionary fields. The fields in the dictionary property hold the values that would be entered in user interface fields on a registration form. To invoke the / atg/store/profile/RegistrationFormHandler form handler, you must include a functional parameter for value.email, value.password, value.confirmPassword, value.firstName, and value.lastName. The following JSON data contains the functional parameters required by the /atg/store/profile/ RegistrationFormHandler form handler.
{ "value.email":"sheroux@example.com", "value.password":"mypassword", "value.confirmPassword":"mypassword", "value.firstName":"Severe", "value.lastName":"Heroux" }
Returning Form Handler Exceptions

Include the atg-rest-return-form-handler-exceptions control parameter with a REST Web Services request to return form handler exceptions in the HTTP response from the server. Set the value of the control parameter to true.
146
The following example shows the response to a REST Web Services request to invoke /atg/userprofiling/ InternalProfileFormHandler/login. The response includes an exceptions element that contains information about the exception that occurred.
<atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class> <exceptions> <formExceptions> <element>Missing value for the login property</element> </formExceptions> </exceptions> <result>true</result> </atgResponse>
The following example shows the response to a successful REST Web Services request to invoke /atg/ userprofiling/InternalProfileFormHandler/login. The response includes an empty exceptions element because no exceptions occurred.
<atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class> <exceptions/> <result>true</result> </atgResponse>
Note: if you choose to include both exceptions and form handler properties in a REST Web Services request, the class element in the atgResponse will contain the following value: class atg.rest.processor.BeanProcessor$FormHandlerPropertiesAndExceptions. See Returning Form Handler Properties (page 147).
Returning Form Handler Properties

Include the atg-rest-return-form-handler-properties control parameter with a REST Web Services request to return the property values of the form handler component. The REST Web Services server will include the property values in a component element in the HTTP response. Set the value of the control parameter to true. The following example shows the response to a REST Web Services request to invoke /atg/store/profile/ RegistrationFormHandler/create. The response includes a component element that contains the property values of the RegistrationFormHandler component.
<atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerProperties</class> <component> <absoluteName>/atg/dynamo/servlet/pipeline/RequestScopeManager/RequestScope-409/ atg/store/profile/RegistrationFormHandler</absoluteName> <addCommerceItemInfos/> <addressIdValueMapKey>addressId</addressIdValueMapKey> [Additional property values omitted to save space]
147
<valueMap>http://myserver:8080/rest/bean/atg/dynamo/servlet/pipeline/ RequestScopeManager/RequestScope-409/atg/store/profile/RegistrationFormHandler/ valueMap</valueMap> <verifyPasswordSuccessURL/> </component> <result>true</result> </atgResponse>
Note: if you choose to include both exceptions and form handler properties in a REST Web Services request, the class element in the atgResponse will contain the following value: class atg.rest.processor.BeanProcessor$FormHandlerPropertiesAndExceptions. See Returning Form Handler Exceptions (page 146).
Form Value Priority

Specify the order in which form values are processed using the atg-rest-form-tag-priorities control parameter. Set the value of the control parameter to a JSON object that assigns an integer value to any of the form values that you wish to prioritize. Higher priority numbers are processed first. Values that you do not prioritize are assigned the priority zero. The following example specifies that the value.password field should be processed before any other field.
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/json" \ -d "{ "value.email": "sheroux@example.com", "value.password": "mypassword", "value.confirmPassword": "mypassword", "value.firstName": "Severe", "value.lastName": "Heroux", "atg-rest-form-tag-priorities": { "value.password": 10 } }" \ http://myserver:8080/rest/bean/atg/store/profile/RegistrationFormHandler/create
148
14 Invoking Java Server Pages (JSPs)
This section provides instructions for using the Oracle ATG Web Commerce platform REST Web Services to invoke Java Server Pages (JSPs) in your Web applications. You can create JSPs that access the functionality of a Web application that would otherwise be difficult to use via REST Web Services. JSPs may combine several functions and return a purpose-built set of information to REST Web Services clients. Note: The REST Web Services interface does not secure access to JSPs. If your JSP provides access to sensitive resources, make sure to include security measures such as an access control servlet in your Web application. The REST Web Services use the URL recoding feature of the Oracle ATG Web Commerce platform. This feature links URL application paths (for example, http://domain/an/application/path/) to specific JSPs in a Web application. It can identify input parameters in the URL and pass them to the JSP. See comprehensive information about URL recoding in the ATG Platform Programming Guide. See instructions for configuring JSPs to be accessed by REST Web Services clients in REST Web Services JSP Configuration Procedure (page 150). To invoke a JSP, send a REST Web Services request as described in the following table.
Value GET or POST Do not submit functional parameters when accessing JSPs via the REST Web Services. Pass parameters in the URL that corresponds to the JSP. The format of the parameters that you pass in the URL is configured by the URL recoding feature of the Oracle ATG Web Commerce platform. The developers who design the JSP and the URL recoding template control the parameter format. See URL Templates for REST Web Services JSPs (page 151).
URL
Include the component pathname that corresponds to the JSP in the application path after /rest/service/. Include the parameters at the end of the path in the format expected by the template. The URL that corresponds to a JSP is configured by the URL recoding feature of the Oracle ATG Web Commerce platform. The developers who design the JSP and the URL recoding template control the URL and the parameter format. See URL Templates for REST Web Services JSPs (page 151).
149
The following example shows a REST Web Services request that invokes a JSP. The application path and parameters in the URL are the controlled by the example configurations shown in URL Templates for REST Web Services JSPs (page 151). The code of the JSP itself is shown in Example REST Web Services JSP (page 152).
$ curl -v -b cookies.txt -X GET http://myserver:7003/rest/service/atg/AnyComponent/ xprod2083,foo * About to connect() to myserver port 7003 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 7003 (#0) > GET /rest/service/atg/AnyComponent/xprod2083,foo HTTP/1.1 > User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5 > Host: myserver:7003 > Accept: */* > Cookie: JSESSIONID=tGD0P6WBTGp62dd5QczJjM0JhpMSvzQvqMbC9jvMNhJ8fS3w33vD!-531422523; DYN_USER_CONFIRM=838bac4608584930c f177410e3b46448; DYN_USER_ID=110001 > < HTTP/1.1 200 OK < Date: Tue, 14 Feb 2012 18:17:34 GMT < Content-Length: 127 < Content-Type: application/json < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMSxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjE= < X-Powered-By: Servlet/2.5 JSP/2.1 < {"displayName":"Wine Glass Set","someString":"foo"} * Connection #0 to host myserver left intact * Closing connection #0
REST Web Services JSP Configuration Procedure

To configure the Oracle ATG Web Commerce platform REST Web Services to make JSPs accessible by REST clients: 1. Add a JSP that generates the output required by the REST Web Services clients that will request it. See information about developing JSPs for Oracle ATG Web Commerce applications in the ATG Page Developer's Guide. Package the JSP in your Web application so that it cannot be accessed by outside visitors. For example, place it under the WEB-INF directory of the Web application. See Example REST Web Services JSP (page 152). 2. Configure a URL template component to link a REST Web Services URL to the JSP. See URL Templates for REST Web Services JSPs (page 151). 3. Add the URL template component to the templates property of the /atg/rest/processor/ ServiceProcessor component. See Configuring the REST ServiceProcessor Component (page 152).
150
URL Templates for REST Web Services JSPs

Use URL templates to link REST Web Services URLs to JSPs. URL templates use regular expressions to recognize input parameters and pass them to a JSP. URL templates are Nucleus components that are used by the URL recoding feature of the Oracle ATG Web Commerce platform. See comprehensive information about that feature in the ATG Platform Programming Guide. To create a URL template component, add a URL template properties file in the configuration path for the Oracle ATG Web Commerce REST Web Services. For example, you could configure a URL template in the file shown below.
<ATG10dir>/home/servers/servername/localconfig/atg/rest/processor/templates/ MyTemplate.properties
An example URL template component properties file is shown below. The urlTemplateFormat property defines the application path of the URL that REST Web Services clients will access. It includes a comma separated list of parameters that the client must supply. The URL format must begin with /rest/service. After that, it must contain the Nucleus path of an existing component in your application. It does not matter which component you choose. The indirectRegex property matches parameters that are supplied in the URL application path. The URL recoding feature will pass these parameters to the JSP. The regexElementList property provides information about each parameter. The two parameters shown in this example are a repository item identifier and a simple string. The forwardUrlTemplateFormat property configures the JSP file that the REST Web Services interface will invoke. The application path includes the context root of the Web application (mymodule in the example). It also includes each parameter that was identified in the URL template as URL parameters that will be passed to the JSP.
$class=atg.repository.seo.IndirectUrlTemplate # Url template format urlTemplateFormat=/rest/service/atg/AnyComponent/{item.id},{mystring} # Regex that matches above format indirectRegex=.*/rest/service/atg/AnyComponent/([^/].*?),([^/].*?)$ # Regex elements regexElementList=item | id | /atg/AnyComponent\:product, mystring | string # Forward Url template forwardUrlTemplateFormat=/mymodule/WEB-INF/rest/myRestJsp.jsp?productId \={item.id}&myString\={mystring} # Web App registry webAppRegistry=/atg/registry/WebApplicationRegistry
Note: See comprehensive information about configuring the URL recoding feature of the Oracle ATG Web Commerce platform in the ATG Platform Programming Guide.
151
Configuring the REST ServiceProcessor Component

Add each URL template component for your REST Web Services JSPs to the templates property of the /atg/ rest/processor/ServiceProcessor component. For example, you could configure the templates property in the file shown below.
<ATG10dir>/home/servers/servername/localconfig/atg/rest/processor/ ServiceProcessor.properties
The example ServiceProcessor.properties file shown below adds a URL template component to the templates property.
templates+=/atg/rest/processor/templates/MyTemplate
Example REST Web Services JSP

This section provides an example of a JSP that returns content to a REST Web Services client. The JSP invokes a servlet bean to return data that it will incorporate into the output it sends to the REST client. In this example, the JSP uses the /atg/commerce/catalog/ProductLookup component to return repository data to the REST client. See comprehensive information about developing JSPs for Oracle ATG Web Commerce application in the ATG Page Developer's Guide.
<%-- Import the dsp tag library to access Oracle ATG Web Commerce functionality. Import tag libraries for the output format you will send to REST clients. --%> <%@ taglib prefix="dsp" uri="http://www.atg.com/taglibs/daf/dspjspTaglib1_1" %> <%@ taglib prefix="json" uri="http://www.atg.com/taglibs/json" %> <%@page contentType="application/json"%> <dsp:page> <%-- Import a servlet bean component you will use with the dsp:droplet element --%> <dsp:importbean bean="/atg/commerce/catalog/ProductLookup"/> <dsp:droplet name="ProductLookup"> <%-- These two parameters are passed to the JSP by the URL recoding template. --%> <dsp:param name="id" param="productId"/> <dsp:param name="aString" param="myString"/> <%-- Write the output for REST clients using the values returned by the servlet bean. --%>
152
<dsp:oparam name="output"> <json:object name="product"> <json:property name="displayName"> <dsp:valueof param="element.displayName"/> </json:property> <json:property name="someString"> <dsp:valueof param="aString"/> </json:property> </json:object> </dsp:oparam> </dsp:droplet> </dsp:page>
153
154
15 Working with Repositories
This section provides instructions for Oracle ATG Web Commerce platform REST Web Services operations involving repositories. A repository item is a JavaBean component that implements atg.repository.RepositoryItem or one of its sub-interfaces, and corresponds to the smallest uniquely identifiable entity in the underlying data store. Each repository item is composed of named properties that store the items datafor example, id, firstName, and lastName.
Listing Repository Items

To list the items of a type in a repository, send a REST Web Services request as described in the following table.
Value GET None Include the component pathname of the repository in the application path after /rest/repository/. Include the name of the item type at the end of the path.
The following example shows a REST Web Services request that lists the repository items of the user item type in the atg/userprofiling/ProfileAdapterRepository repository.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user * * * > > > > > About to connect() to myserver port 8080 (#0) Trying 12.34.567.890... connected Connected to myserver (12.34.567.890) port 8080 (#0) GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user HTTP/1.1 User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 Host: myserver:8080 Accept: */* Cookie: DYN_USER_ID=140001; JSESSIONID=46E252A84E611BCD06710FD6A0FBA5A4; DYN_USER_CONFIRM=2a952017db56aab256c7e7077bf1feec
155
> < < < <
HTTP/1.1 200 OK Server: Apache-Coyote/1.1 X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc 2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Fri, 29 Oct 2010 16:27:49 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <user> <element>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/user/se-570040</element> <element>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/user/120001</element> <element>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/user/140001</element> </user> </atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
Retrieving a Repository Item

To list the properties of a repository item, send a REST Web Services request as described in the following table.
Value GET None Include the component pathname of the repository in the application path after /rest/repository/. Include the name of the item type and the identifier of the specific item at the end of the path.
The following example shows a REST Web Services request that lists the properties of a specific repository item of the user item type in the /atg/userprofiling/ProfileAdapterRepository repository.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/ user/130001/ * About to connect() to myserver port 8080 (#0)
156
* * > > > > > > < < < <
Trying 12.34.567.890... connected Connected to myserver (12.34.567.890) port 8080 (#0) GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/ HTTP/1.1 User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 Host: myserver:8080 Accept: */* Cookie: DYN_USER_ID=140001; JSESSIONID=46E252A84E611BCD06710FD6A0FBA5A4; DYN_USER_CONFIRM=2a952017db56aab256c7e7077bf1feec
HTTP/1.1 200 OK Server: Apache-Coyote/1.1 X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc 2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Fri, 29 Oct 2010 16:40:51 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <repositoryId>130001</repositoryId> <securityStatus>4</securityStatus> [Additional property values omitted to save space] <ThirtySomethings>false</ThirtySomethings> <MenOnly>false</MenOnly> <Fashionista>false</Fashionista> <Young>false</Young> <WomenOnly>false</WomenOnly> </atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
Retrieving a Specific Property

To retrieve a specific property of a repository item, send a REST Web Services request as described in the following table.
Value GET None Include the component pathname of the repository in the application path after /rest/repository/. Include the name of the item type, the identifier of the specific item, and the name of the property at the end of the path.
157
The following example shows a REST Web Services request that returns the lastPurchaseDate property of a specific repository item of the user item type in the atg/userprofiling/ProfileAdapterRepository repository.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/ user/130001/lastPurchaseDate * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/ lastPurchaseDate HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: DYN_USER_ID=140001; JSESSIONID=46E252A84E611BCD06710FD6A0FBA5A4; DYN_USER_CONFIRM=2a952017db56aab256c7e7077bf1feec > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 * Replaced cookie JSESSIONID="A8D99275B90B200E0913A8831E77A9F4" for domain myserver, path /, expire 0 < Set-Cookie: JSESSIONID=A8D99275B90B200E0913A8831E77A9F4; Path=/ < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc 2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Fri, 29 Oct 2010 19:42:35 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <lastPurchaseDate>2010-10-27</lastPurchaseDate> </atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
Performing RQL Queries

To perform a Repository Query Language (RQL) query, send a REST Web Services request as described in the following table. See information about repository queries in ATG Repository Guide.
Request Component HTTP Method
Value GET
158
Request Component Functional Parameters
Value Include the atg-rest-rql functional parameter. Set its value to the RQL query you want to execute. If you include this parameter as a URL query string, make sure that you URL encode the RQL query. For example, the query ALL RANGE +4 should be encoded as ALL+RANGE+%2B4.
URL
Include the component pathname of the repository item type that you want to query in the application path after /rest/repository/.
The following example shows a REST Web Services request that performs an RQL query. It returns the first four items of item type product in the /atg/commerce/catalog/ProductCatalog repository.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/repository/atg/commerce/catalog/ProductCatalog/product?atgrest-rql=ALL+RANGE+%2B4 * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > GET /rest/repository/atg/commerce/catalog/ProductCatalog/product?atg-rest-rql=ALL +RANGE+%2B4 HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: DYN_USER_ID=140003; JSESSIONID=0D62D5F5145D6A1E7A2EDBC669F3BA0F; DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybU xpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Fri, 29 Oct 2010 21:33:00 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <product> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ProductCatalog/ product/xprod2022</element> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ProductCatalog/ product/xprod1064</element> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ProductCatalog/ product/xprod2024</element> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ProductCatalog/ product/xprod1066</element> </product> </atgResponse> * Connection #0 to host myserver left intact
159
* Closing connection #0
Note: You can include the atg-rest-rql functional parameter in the message body of a POST HTTP request if you prefer not to URL encode your RQL queries. Use the atg-rest-view control parameter to instruct the REST Web Services server to handle your POST request as a GET request. See Handling POST Requests as Other Methods (page 108). Note: Do not include parameters in the RQL queries that you perform via the REST Web Services. Make sure that all constants are explicitly included in the RQL statements. See information about parameters in RQL queries in the ATG Repository Guide.
Adding a Repository Item

To add a repository item, send a REST Web Services request as described in the following table.
Value POST Include all required property values for the new repository item as functional parameters with the REST Web Services request. Include the component pathname of the repository in the application path after /rest/repository/. Include the name of the item type at the end of the path.
URL
The following example shows a REST Web Services request that creates a new repository item in the /atg/ userprofiling/ProfileAdapterRepository repository. The returned data includes all the property values for the new item.
curl -v -b cookies.txt -X POST -H "Content-Type: application/xml" \ -d "<parameters><login>rbriere</login><lastName>Briere</lastName><firstName>Roland</ firstName><email>rbriere@example.com</email><password>mypassword</password></ parameters>" \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user * * * > > > > > About to connect() to myserver port 8080 (#0) Trying 12.34.567.890... connected Connected to myserver (12.34.567.890) port 8080 (#0) POST /rest/repository/atg/userprofiling/ProfileAdapterRepository/user HTTP/1.1 User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 Host: myserver:8080 Accept: */* Cookie: DYN_USER_ID=140003; JSESSIONID=F9C672B8E52D2033A1B70C4EE225577F; DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b > Content-Type: application/xml > Content-Length: 168 >
160
< < < <
HTTP/1.1 201 Created Server: Apache-Coyote/1.1 X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9 ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Mon, 01 Nov 2010 17:35:29 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <repositoryId>130030</repositoryId> <securityStatus>4</securityStatus> [Additional property values omitted to save space] <lastPurchaseDate/> <lastName>Briere</lastName> <gender>unknown</gender> <salePriceList/> <categoryLastBrowsed/> [Additional property values omitted to save space] <registrationDate>2010-11-01 13:35:28.742</registrationDate> <dateOfBirth/> <member>false</member> <firstName>Roland</firstName> <billingAddress/> [Additional property values omitted to save space] <Young>false</Young> <WomenOnly>false</WomenOnly> </atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
Transient Items
Use the atg-rest-transient control parameter to create transient repository items. Set the value of the parameter to true. The following command creates a transient repository item.
curl -v -b cookies.txt -X POST -H "Content-Type: application/xml" \ -d "<parameters><login>agold</login><lastName>Gold</lastName> <firstName>Abbey</firstName><email>agold@example.com</email> <password>mypassword</password></parameters>" \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user? atg-rest-transient=true
161
Setting Repository Item Properties

To update properties of a repository item, send a REST Web Services request as described in the following table.
Value PUT Include the new values for each property you are updating as functional parameters with the REST Web Services request. Include the component pathname of the repository in the application path after /rest/repository/. Include the name of the item type and the item identifier at the end of the path.
URL
The following example shows a REST Web Services request that updates two properties of an existing repository item in the /atg/userprofiling/ProfileAdapterRepository repository.
curl -v -b cookies.txt -X PUT \ -H "Content-Type: application/xml" \ -d "<parameters><middleName>Desire</middleName><email>agoldie@example.com</email></ parameters>" \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/ user/130034 * * * > > > > > About to connect() to myserver port 8080 (#0) Trying 12.34.567.890... connected Connected to myserver (12.34.567.890) port 8080 (#0) PUT /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130034 HTTP/1.1 User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 Host: myserver:8080 Accept: */* Cookie: DYN_USER_ID=140003; JSESSIONID=B6D3509A03881D9CE1A1370434AD18CB; DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b > Content-Type: application/xml > Content-Length: 90 > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 * Replaced cookie JSESSIONID="6A9888BA9F4035AF606AE7E40A435451" for domain myserver, path /, expire 0 < Set-Cookie: JSESSIONID=6A9888BA9F4035AF606AE7E40A435451; Path=/ < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm 9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Mon, 01 Nov 2010 19:40:41 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse>true</atgResponse>
162
* Connection #0 to host myserver left intact * Closing connection #0
Deleting a Repository Item

To delete a specific repository item, send a REST Web Services request as described in the following table.
Value DELETE Include the new values for each property you are updating as functional parameters with the REST Web Services request. Include the component pathname of the repository in the application path after /rest/repository/. Include the name of the item type and the item identifier at the end of the path.
URL
The following example shows a REST Web Services request that deletes an existing repository item in the /atg/ userprofiling/ProfileAdapterRepository repository.
curl -v -b cookies.txt -X DELETE \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/ user/130037 * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > DELETE /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130037 HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: DYN_USER_ID=140003; JSESSIONID=E8FF855FEF5C59ECF6FA9D1A69F1C30D; DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b > < HTTP/1.1 410 Gone < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 < X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9 ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Mon, 01 Nov 2010 20:21:19 GMT < <?xml version="1.0" encoding="UTF-8"?>
163
<atgResponse>true</atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
164
16 Property Filtering
The Oracle ATG Web Commerce platform REST Web Services include functionality that filters properties from output. Use this functionality to: Mark a property in a Nucleus component or repository item as hidden or not writable. Configure the system to override the default functionality of outputting all items and instead output only the items defined in the filtering configuration file. Add your own custom properties for components or repository items and specify the sources of their values. An extension of the property filtering feature, called property aliasing, allows you to create virtual components with properties that assemble values from a variety of sources.
Default Filtering
The filtering configuration file is located at /atg/rest/filtering/filteringConfiguration.xml in your Oracle ATG Web Commerce platform servers configuration path. To customize it, create that file in your own module and the servers XML combination functionality will combine all the filteringConfiguration.xml files. Include component elements in the file to configure the filtering applied to requests for Nucleus components and repositories. Set the name attribute of the component element to a Nucleus component path, a repository path, or a fully qualified Java class or interface name. If you enter a Java class or interface name, the filtering behavior will apply to objects that are subclasses or implementations of it. Filters for Nucleus component paths override filters for Java classes and implementations. Only one filter can apply to a request for an object. The following sample makes one property hidden and another writable in a Nucleus component and a repository item: property1 and repProperty1 are both hidden and will not be returned in the output whenever the Nucleus component or that specific property is requested. property2 and repProperty2 cannot be changed by a REST request. (Note that the writable flag affects only REST requests.)
<rest-filtering> <component name="/some/Component" default-include="true"> <property name="property1" hidden="true"/> <property name="property2" writable="false"/> </component>
165
<component name="/some/Repository" default-include="true"> <item-descriptor name="anItemDescriptorName"> <property name="repProperty1" hidden="true"/> <property name="repProperty2" writable="false"/> </item-descriptor> </component> </rest-filtering>
The default-include attribute tells the server that it should return only the values specified inside this component tag and ignore all other properties of the Nucleus component or repository item. The following sample adds additional properties which do not exist in the Nucleus component or repository item. The sample also configures where the values for these virtual properties come from. The property called virtual1 does not exist in the /some/Component bean. Its value, specified by the target attribute, is the value of property2 in the same object. Similarly, the repVirtual1 property returns the value of repProperty2 as its value. The target attribute also allows for subproperties to be specified, as the sample demonstrates for the virtual2 and repVirtual2 properties. Note that the dot notation can be more than one level deep.
<rest-filtering> <component name="/some/Component" default-include="true"> <property name="property1" hidden="true"/> <property name="property2" writable="false"/> <property name="virtual1" target="property2"/> <property name="virtual2" target="property2.subproperty"/> </component> <component name="/some/Repository" default-include="true"> <item-descriptor name="anItemDescriptorName"> <property name="repProperty1" hidden="true"/> <property name="repProperty2" writable="false"/> <property name="repVirtual1" target="repProperty2"/> <property name="repVirtual2" target="repProperty2.subproperty"/> </item-descriptor> </component> </rest-filtering>
The next sample extends the previous one by adding a component attribute to the property tag and using that in combination with the target tag. This demonstrates how the value of a property can come from another Nucleus component. (Note that the component attribute can only reference a Nucleus component.) Dot notation can be used in the target attribute when the component attribute is used.
<rest-filtering> <component name="/some/Component" default-include="true"> <property name="property1" hidden="true"/> <property name="property2" writable="false"/> <property name="virtual1" target="property2"/> <property name="virtual2" target="property2.subproperty"/> <property name="virtual3" component="/some/other/Component" target="aProperty"/> </component> <component name="/some/Repository" default-include="true">
166
<item-descriptor name="anItemDescriptorName"> <property name="repProperty1" hidden="true"/> <property name="repProperty2" writable="false"/> <property name="repVirtual1" target="repProperty2"/> <property name="repVirtual2" target="repProperty2.subproperty"/> <property name="repVirtual3" component="/some/other/Component" target="aProperty"/> </item-descriptor> </component> </rest-filtering>
Finally, if you need to write custom code to specify your value, then you must use the property-customizer attribute, as shown in the following sample.
<rest-filtering> <component name="/some/Component" default-include="true"> <property name="property1" hidden="true"/> <property name="property2" writable="false"/> <property name="virtual1" target="property2"/> <property name="virtual2" target="property2.subproperty"/> <property name="virtual3" component="/some/other/Component" target="aProperty"/> <property name="virtual4" property-customizer="some.class.Here"/> </component> <component name="/some/Repository" default-include="true"> <item-descriptor name="anItemDescriptorName"> <property name="repProperty1" hidden="true"/> <property name="repProperty2" writable="false"/> <property name="repVirtual1" target="repProperty2"/> <property name="repVirtual2" target="repProperty2.subproperty"/> <property name="repVirtual3" component="/some/other/Component" target="aProperty"/> <property name="repVirtual4" property-customizer="some.class.Here"/> </item-descriptor> </component> </rest-filtering>
When using the property-customizer attribute, the value should be the name of a class which implements the atg.rest.filtering.RestPropertyCustomizer interface, shown below.
public Object getPropertyValue(String pPropertyName, Object pResource); public void setPropertyValue(String pPropertyName, Object pValue, Object pResource);
You can also set the property-customizer attribute to a Nucleus component path. The component must be an instance of a class that implements the atg.rest.filtering.RestPropertyCustomizer interface.
Specifying the Filter Depth

You can control the nested level at which a filter will be applied. The number of nested levels at which the filter is applied is the filter depth. A filter depth of zero indicates that the filter should apply only to the immediate properties of the component the filter is configured for. A filter depth of one indicates that the filter should apply to the first nested level of properties. To set the filter depth for a repository, add the depth attribute to the item-descriptor element. For example:
<component name="/atg/userprofiling/ProfileAdapterRepository"
167
default-include="false"> <item-descriptor name="user" depth="1"> <property name="wishlist" hidden="false"/> <property name="creditCards" hidden="false"/> </item-descriptor> </component>
To set the filter depth for a non-repository component, add the depth attribute to the component element. For example:
<component name="/atg/resttest/BeanTest" depth="0" default-include="false"> <property name="repository" hidden="false"/> </component>
Filtering Templates
You can configure property filtering templates that will be applied when REST requests invoke them. Configure filtering templates for specific Nucleus components, repositories, or Java classes in the /atg/rest/filtering/ filteringConfiguration.xml file, just as you would for default filtering. See Default Filtering (page 165). Include a template element in the rest-filtering element for each template you want to configure. Add an id attribute to the template element. REST clients will refer to this id value when invoking the template. Configure the filtering behavior of the template using the same elements and syntax that you would in a component element for default filtering. See Default Filtering (page 165). The following filteringConfiguration.xml file defines a filtering template.
<rest-filtering> <template id="myfiltertemplate" name="/atg/MyDog" default-include="true"> <property name="tricks" hidden="true" /> </template> </rest-filtering>
Invoke filtering templates with the atg-rest-property-filter-templates control parameter. Include the id of a template or a JSON array of ids as the value of this parameter. The following REST request invokes the filtering template configured in the example above.
curl -v -b cookies.txt -X GET \ http://myserver:7003/rest/bean/atg/MyDog?atg-rest-property-filtertemplates=myfiltertemplate
The following REST request invokes multiple filtering templates.
curl -v -b cookies.txt -X GET \
168
http://myserver:7003/rest/bean/atg/MyDog?atg-rest-property-filtertemplates=["userFilter","wishlistFilter"]
Filtering for One Request

Use the atg-rest-property-filters control parameter to apply property filtering to individual REST Web Services requests. The value of the control parameter uses the same format as the rest-filtering element in the / atg/rest/filtering/filteringConfiguration.xml configuration file. See Default Filtering (page 165). If you include the atg-rest-property-filters control parameter in a REST request, the configurations that you have made in the filteringConfiguration.xml file will not apply at all. The REST interface considers only the per-request filter. If you include the atg-rest-property-filters control parameter in a REST request, all properties are hidden by default. You must explicitly set the hidden attribute to false for each property that you wish to return. Use JSON markup for the atg-rest-property-filters value. The components of the JSON value are shown below.
{ "<componentName>": [ { "item-descriptor": "<itemDescriptorName>", "depth": <depthInt>, "properties": { "<propertyName>": { "hidden": <boolean>, "writable": <boolean>, "target": "<target-dot-notation>", "component": "<component-path>", "property-customizer": "<customizer-class-name>" }, ... }, ... }, ... ], ... }
For example, the following atg-rest-property-filters control parameter value specifies that only the wishlist property will be returned for user repository items. It also specifies that only the eventType and published values will be returned for the wishlist property.
{ "/atg/userprofiling/ProfileAdapterRepository": [ { "item-descriptor": "user", "depth": 0, "properties": { "wishlist": {
169
} } } ], "/atg/commerce/gifts/Giftlists": [ { "item-descriptor": "gift-list", "depth": 1, "properties": { "eventType": { }, "published": { } } } ] }
The REST Web Service server will check several configuration parameters before accepting filters supplied with the atg-rest-property-filters control parameter. These configuration properties control whether certain types of per-request filtering will be accepted. There are individual configuration properties for requests that will return JSON and XML output. See information about the following properties in /atg/rest/output/ JSONOutputCustomizer (page 174) and /atg/rest/output/XMLOutputCustomizer (page 176). enablePerRequestFilters enablePerRequestComponentFilters enablePerRequestRepositoryFilters enablePerRequestClassFilters
Property Aliasing
Property aliasing allows you to create virtual components with properties that assemble values from a variety of sources. Use virtual components to gather data from a variety of sources and return it in a single REST Web Services request. To create a virtual component with property aliasing: 1. Add a component element to the /atg/rest/filtering/filteringConfiguration.xml configuration file for your Oracle ATG Web Commerce platform server. Specify the Nucleus path for the virtual component in the name attribute of that element. 2. Include one or more property elements in the component element. Either draw the value of the component from another component property using the component and target attributes or from a custom class using the property-customizer attribute. The following example configuration creates a virtual component. It specifies the name of a component that does not exist in the name attribute of the component tag, thus creating a virtual component. When creating virtual components in this way, do not use the item-descriptor element.
170
When a REST client requests this component, the list of properties that are specified inside the component element will be rendered.
<rest-filtering> <component name="/some/nonexisting/Component"> <property name="property1" component="/some/other/Component" target="aProperty"/> <property name="property2" property-customizer="some.class.Here"/> </component> <rest-filtering>
Suppressing Property Expansion

You can configure the Oracle ATG Web Commerce platform REST Web Services interface to return only the string representation of specific properties. This can be useful when you need to set the return depth to a level that returns certain deeply-nested properties but you do not want extensive, unnecessary detail for other properties. See Return Depth (page 134). Suppress property expansion to return only the string representation. The following example output shows the string representation of a timestamp value.
"creationDate": "2008-10-21 16:52:00.0"
The following example output shows a timestamp value that has been expanded.
"creationDate": { "class": "class java.sql.Timestamp", "date": 21, "day": 2, "hours": 16, "minutes": 52, "month": 9, "nanos": 0, "seconds": 0, "time": 1224622320000, "timezoneOffset": 240, "year": 108 },
See instructions for suppressing property expansion in the following sections: Suppressing Property Expansion for Java Classes (page 171) Suppressing Property Expansion for Specific Properties (page 172)
Suppressing Property Expansion for Java Classes

You can suppress property expansion for properties that have specific Java classes as their data types.
171
1. Add the fully qualified Java class name of each Java class that you want to suppress property expansion for. Separate class names with commas.
nonExpandableClassesList=java.util.Date,java.sql.TimeStamp
2. Set the ignoreExpandableOutputForSpecificClasses property of the /atg/rest/filtering/ FilteringManager component to true.
Suppressing Property Expansion for Specific Properties

You can suppress property expansion for specific properties. 1. Add the property to the filteringConfiguration.xml file. See Default Filtering (page 165). 2. Include the expand attribute in the property element. Set the value of the attribute to false.
<rest-filtering> <component name="/atg/commerce/catalog/ProductCatalog" default-include="true"> <item-descriptor name="product"> <property name="creationDate" expand="false"/> </item-descriptor> </component> </rest-filtering>
Filtering Priority
You can apply property filtering for REST requests at three levels: default filtering, filtering templates, and perrequest filtering. The REST Web Services server gives priority to filters according to these levels in the following order. 1. Per-request filtering 2. Filtering templates 3. Default filtering For example, if default filtering specifies that a property should be hidden and a per-request filter specifies that it is not hidden, the per-request filtering has priority. The property value will be returned in the results.
172
17 Configuring the REST Server
Configure the Oracle ATG Web Commerce platform REST Web Services by setting the parameters described in the following sections.
/atg/rest/Configuration
This section explains configuration properties that are set on the /atg/rest/Configuration component.
defaultOutputCustomizer
This configuration property controls the markup that the REST Web Services server uses for returned data. See Choosing Output Markup (page 126). The following example specifies that the server should use XML format for the data it returns.
defaultOutputCustomizer=/atg/rest/output/XMLOutputCustomizer
maxDepthAllowed
This configuration property controls the maximum number of nested property levels that you can expand in returned data. See Expanding Multiple Values and Complex Objects (page 129). The following example specifies that only three nested levels may be expanded.
maxDepthAllowed=3
/atg/rest/processor/BeanProcessor
This section explains configuration properties that are set on the /atg/rest/processor/BeanProcessor component.
173
returnFormHandlerExceptionsByDefault
This configuration property controls whether the REST Web Services server will return information about the exceptions it encounters while invoking form handlers. See Returning Form Handler Exceptions (page 146). The following example specifies that exceptions should be included in the HTTP response to a Web Services request.
returnFormHandlerExceptionsByDefault=true
returnFormHandlerPropertiesByDefault
This configuration property controls whether the REST Web Services server will return the properties of the form handler components it invokes. See Returning Form Handler Properties (page 147). The following example specifies that the form handler properties should be included in the HTTP response to a Web Services request.
returnFormHandlerPropertiesByDefault=true
/atg/rest/output/JSONOutputCustomizer
This section explains configuration properties that are set on the /atg/rest/output/ JSONOutputCustomizer component.
enableFormatDateOutput for JSON

This configuration property specifies whether the REST Web Services server will return date properties in the following format:
If this property is set to true, dates will be returned in this format. If the property is set to false, dates will be returned as a string representation of the java.util.Date object. See Date Format in Returned Data (page 135).
enablePerRequestFilters for JSON

This configuration property controls whether the REST Web Services server will accept filtering control parameters that are presented with REST requests. See Property Filtering (page 165). This property affects requests that will return results formatted with JSON markup. See Choosing Output Markup (page 126). If this property is set to true, the server will accept the control parameters. If it is set to false the server will ignore them.
174
enablePerRequestComponentFilters for JSON

This configuration property controls whether the REST Web Services server will accept filtering control parameters that affect Nucleus components when they are presented with REST requests. See Property Filtering (page 165). This property affects requests that will return results formatted with JSON markup. See Choosing Output Markup (page 126). If this property is set to true, the server will accept the control parameters. If it is set to false the server will ignore them.
enablePerRequestRepositoryFilters for JSON

This configuration property controls whether the REST Web Services server will accept filtering control parameters that affect repositories when they are presented with REST requests. See Property Filtering (page 165). This property affects requests that will return results formatted with JSON markup. See Choosing Output Markup (page 126). If this property is set to true, the server will accept the control parameters. If it is set to false the server will ignore them.
enablePerRequestClassFilters for JSON

This configuration property controls whether the REST Web Services server will accept filtering control parameters that affect components that subclass or implement specific Java classes when they are presented with REST requests. See Property Filtering (page 165). This property affects requests that will return results formatted with JSON markup. See Choosing Output Markup (page 126). If this property is set to true, the server will accept the control parameters. If it is set to false the server will ignore them.
showRestPaths for JSON

This configuration property specifies whether the REST Web Services server will return complex property values as Nucleus paths or by including the actual complex data in an HTTP response. See Expanding Multiple Values and Complex Objects (page 129). Setting the showRestPaths property on the /atg/rest/output/JSONOutputCustomizer component only affects returned data that is formatted using JSON markup. The following example specifies that multiple values and complex objects should be expanded in returned data.
showRestPaths=false
175
/atg/rest/output/XMLOutputCustomizer
This section provides information about configuration properties that may be set on the /atg/rest/output/ XMLOutputCustomizer component.
enableFormatDateOutput for XML

This configuration property specifies whether the REST Web Services server will return date properties in the following format:
If this property is set to true, dates will be returned in this format. If the property is set to false, dates will be returned as a string representation of the java.util.Date object. See Date Format in Returned Data (page 135).
enablePerRequestFilters for XML

This configuration property controls whether the REST Web Services server will accept filtering control parameters that are presented with REST requests. See Property Filtering (page 165). This property affects requests that will return results formatted with XML markup. See Choosing Output Markup (page 126). If this property is set to true, the server will accept the control parameters. If it is set to false the server will ignore them.
enablePerRequestComponentFilters for XML

This configuration property controls whether the REST Web Services server will accept filtering control parameters that affect Nucleus components when they are presented with REST requests. See Property Filtering (page 165). This property affects requests that will return results formatted with XML markup. See Choosing Output Markup (page 126). If this property is set to true, the server will accept the control parameters. If it is set to false the server will ignore them.
enablePerRequestRepositoryFilters for XML

This configuration property controls whether the REST Web Services server will accept filtering control parameters that affect repositories when they are presented with REST requests. See Property Filtering (page 165). This property affects requests that will return results formatted with XML markup. See Choosing Output Markup (page 126).
176
If this property is set to true, the server will accept the control parameters. If it is set to false the server will ignore them.
enablePerRequestClassFilters for XML

This configuration property controls whether the REST Web Services server will accept filtering control parameters that affect components that subclass or implement specific Java classes when they are presented with REST requests. See Property Filtering (page 165). This property affects requests that will return results formatted with XML markup. See Choosing Output Markup (page 126). If this property is set to true, the server will accept the control parameters. If it is set to false the server will ignore them.
showRestPaths for XML

This configuration property specifies whether the REST Web Services server will return complex property values as Nucleus paths or by including the actual complex data in an HTTP response. See Expanding Multiple Values and Complex Objects (page 129). Setting the showRestPaths property on the /atg/rest/output/XMLOutputCustomizer component only affects returned data that is formatted using XML. The following example specifies that multiple values and complex objects should be expanded in returned data.
showRestPaths=false
/atg/rest/processor/RepositoryProcessor
This section explains configuration properties that are set on the /atg/rest/processor/ RepositoryProcessor component.
acceptJSONInput
This configuration property specifies whether the REST Web Services server will accept standard JSON markup for setting collection or map values on repository item properties. See JSON Markup Input for Multiple Value Repository Item Properties (page 121). The following example specifies that the REST Web Services server will accept JSON markup for setting multiple value repository item properties.
acceptJSONInput=true
177
appendMultiValuesByDefault
This configuration property specifies whether the values you set in repository item properties should be added to an existing set of values or should replace them. This only applies to repository item properties that accept multiple values. See Multiple Values in Input (page 119). The following example specifies that values set in a repository item property that holds multiple values should be added to the existing list. The existing values will remain set.
appendMultiValuesByDefault=true
/atg/rest/processor/RestSecurityProcessor
This section explains configuration properties that are set on the /atg/rest/processor/RestSecurityProcessor component.
allowAccessForUnsecuredRepository
This configuration property specifies whether the REST Web Services server will allow clients to get or set properties in unsecured repositories. Allowing this access is not recommended in a production environment. Configure repository security before allowing REST Web Services clients to interact with repositories. See Repository Security (page 182). The following example specifies that any REST Web Services client may get or set properties in unsecured repositories. Use this setting for testing only.
allowAccessForUnsecuredRepository=true
178
18 Security for REST Web Services
This section provides information about the way the Oracle ATG Web Commerce platform REST Web Services server secures its interface and how it interacts with the underlying security system for the Oracle ATG Web Commerce platform in general.
Security Overview
The Oracle ATG Web Commerce platform REST Web Services server uses the underlying security system of the Oracle ATG Web Commerce platform. HTTP clients that invoke REST Web Services functionality behave in a manner that is similar to human users logging into an Oracle ATG Web Commerce platform user interface and interacting with its functionality. To understand the security system used by the REST Web Services server you must understand the system used by the Oracle ATG Web Commerce platform. See Managing Access Control in the ATG Platform Programming Guide.
Logging In and Session IDs

The REST Web Services server will only process requests if the HTTP client sending them has an active HTTP session. Clients must log in to the server before performing operations. The server will provide a session ID which the client must present with each REST Web Services request. See Logging In (page 108).
Nucleus Component Granularity

The security functionality for Oracle ATG Web Commerce platform REST Web Services allows security to be placed on multiple levels of granularity for Nucleus components. The default configuration for Oracle ATG Web Commerce platform REST Web Services is to not allow access to any components. This means that you will need to configure security to be able to call methods or access properties on Nucleus components. Security on Nucleus components can be configured globally for all components, at the component level for all properties and methods, at the property level, at the method level, and for entire Nucleus sub-trees. The REST security subsystem depends on the Oracle ATG Web Commerce security system and therefore uses ACLs which are similar to those used to configure security in other parts of an Oracle ATG Web Commerce server. The personas can be users, organizations, or roles. The valid rights which can be assigned to a persona are read, write, and execute. Read and write refer to Nucleus properties and execute refers to Nucleus methods. To configure multiple personas, use a semicolon (;) character to separate each access control entry (persona/rights).
179
The REST security configuration file is located at /atg/rest/security/restSecurityConfiguration.xml. To add your own security configuration create a file at that location in the config directory of your module. Note: The Oracle ATG Web Commerce platform REST Web Services module does not provide functionality for securing repository items All Oracle ATG Web Commerce repository security is handled by the Oracle ATG Web Commerce secured repository system, which works in conjunction with the Oracle ATG Web Commerce Security System to provide fine-grained access control to repository item descriptors, individual repository items, and even individual properties. For more information, see the ATG Repository Guide.
Quick Setup for Testing

Once the server is running with the REST module, your platform is now able to accept and process REST requests. Before you begin coding, you must configure the Web Services security component. By default: The security components in the Oracle ATG Web Commerce platform REST Web Services require you to be logged into the server in order to make calls. No users have access to any components, so even a logged-in user will not be able to successfully make any REST requests. In a development environment, you can set a default ACL in the security configuration file. This allows all the specified users to have access to all Nucleus components. Important: This functionality is provided for convenience and should not be used in a production environment unless that is the specified intent. To set a default ACL in the security configuration layer, create a file in your localconfig directory at atg/ rest/security named restSecurityConfiguration.xml. Add the following lines to the file, replacing #username# with the name of a valid profile for logging onto your Oracle ATG Web Commerce system.
<rest-security> <default-acl value="Profile$login$#username#:read,write,execute"/> </rest-security>
Global Security
To configure global security, use the default-acl tag. This tag defines which personas have access to Nucleus components. In the following example, all users who are assigned the restUser role have read and write access to all Nucleus properties and execute access for all methods on Nucleus components. The defaultacl tag is optional. This example assumes that a role called restUser has already been created in the profile repository.
<rest-security> <default-acl value="Profile$role$restUser:read,write,execute"/> </rest-security>
180
Component Security
To configure security on a specific component, use the resource tag. This tag, along with the component attribute, allows you to define which users have access to the specified component. You could disable security entirely for the specified component by using the optional secure attribute. In the following example, the /some/Component component is configured so that only the user whose login is restAdmin has full access to it; users with the restUser role only have read access. In addition, the /some/ other/Component component is configured to disable security. This means that all users have full access to all properties and methods of that component.
<rest-security> <default-acl value="Profile$role$restUser:read,write,execute"/> <resource component="/some/Component"> <default-acl value="Profile$login$restAdmin:read,write,execute;Profile$role$restUser:read"/> </resource> <resource component="/some/other/Component" secure="false"/> </rest-security>
Property and Method Security

To configure security on a component property or method, add a property or method tag within the resource tag. The property and method tags allow you to control which users have access to specific properties and methods. In the following example, property1 and methodA in /some/Component can be accessed only by the restAdmin user. property2 and methodB can be accessed by anyone, because security has been disabled on it.
<rest-security> <default-acl>Profile$role$restUser:read,write,execute"</default-acl> <resource component="/some/Component"> <default-acl value="Profile$login$restAdmin:read,write,execute;Profile$role $restUser:read"/> <property name="property1"> <acl value="Profile$login$restAdmin:read,write"/> </property> <property name="property2" secure="false"/> <method name="methodA"> <acl value="Profile$login$restAdmin:execute"/> </property> <method name="methodB" secure="false"/> </resource>
181
<resource component="/some/other/Component" secure="false"/> </rest-security>
Methods which are overloaded and have different security requirements require a signature attribute, available on the method tag. This attribute allows for a Java method signature that uniquely identifies the method.
Repository Security
The Oracle ATG Web Commerce platform REST Web Services module does not provide functionality for securing repository items. If you need to provide access to repository data to REST Web Services clients, use one of the following options: Implement a Java Server Page (JSP) to access and return the repository data to REST clients. See Invoking Java Server Pages (JSPs) (page 149). If your JSP provides access to sensitive resources, make sure to include security measures such as an access control servlet in your Web application. Use the secured repository system, which works in conjunction with the Oracle ATG Web Commerce security system to provide fine-grained access control to repository item descriptors, individual repository items, and even individual properties. For more information, refer to the ATG Repository Guide
Securing Groups of Components

The Oracle ATG Web Commerce platform REST Web Services provide the ability to secure groups of components within the same Nucleus sub-tree. This is accomplished by using the * wildcard character. Note that * is the only wildcard character allowed. The following example sets the ACL for all components within the /atg/commerce sub tree to be accessible only by users with the restCommerceUser role.
<rest-security> <default-acl>Profile$role$restUser:read,write,execute"</default-acl> <resource component="/atg/commerce/*"> <default-acl value="Profile$role$restCommerceUser:read,write,execute"/> </resource> </rest-security>
182
19 ATG Client Libraries
The Oracle ATG Web Commerce platform REST Web Services package includes two client libraries: Java Client Library (page 183) ActionScript Client Library (page 197) These libraries make Oracle ATG Web Commerce platform REST Web Services easier to use by hiding the complexity of creating connections, assembling payloads for requests, and processing responses.
Java Client Library

The Java client library provides a number of classes that assist in making REST calls to the Oracle ATG Web Commerce platform REST Web Services. The following classes are the ones youll use most often:
RestSession
Handles login and logout, manages connections, and issues requests.

RestResult
Accesses the RestResult object that is returned when a request is made to the server. This class also includes convenience methods for retrieving the response data.
RestComponentHelper
Contains a series of static helper methods that simplify issuing Nucleus component calls to the server.
RestRepositoryHelper
Contains a series of static helper methods that simplify issuing repository calls to the server.
Creating Requests
You will find it easiest to make most Oracle ATG Web Commerce platform REST Web Services requests with the RestComponentHelper and RestRepositoryHelper classes. These two classes simplify calling into the server by providing methods which hide the complexity of assembling the data for the request. All the methods for both classes are static and each returns a RestResult object and throws RestClientException. See the Javadoc for more information about each method.
183
atg.rest.client.RestComponentHelper
The methods of the RestComponentHelper class allow access to components, properties, and methods. Each of the methods accepts a Map of parameters, which control the request. For more information and examples, see Accessing Components with the Java Client Library (page 192). public static RestResult getComponent(String pComponentPath, Map<String,Object>
pParams, RestSession pSession)
Returns all the properties of the specified Nucleus component. public static RestResult getPropertyValue(String pComponentPath, String pProperty,
Map<String,Object> pParams, RestSession pSession)
Returns the requested property from the specified Nucleus component. public static RestResult setPropertyValue(String pComponentPath, String pProperty,
Object pValue, Map<String,Object> pParams, RestSession pSession)
Sets a value on the specified Nucleus component property. public static RestResult executeMethod(String pComponentPath, String pMethodName,
Object[] pArguments, Map<String,Object> pParams, RestSession pSession)
Calls a public method on the specified Nucleus component. The Object[] pArguments parameter is an array of method arguments. This parameter should contain one Object for each of the method parameters. For example, if the method takes an int, then a java.lang.Integer object should be passed. The Java client library handles converting the object for transport to the server and the Oracle ATG Web Commerce REST module handles converting it to an int. If any parameter object is passed as a String, the parameter will be transported to the server without any changes. This means that a method that takes an int can have a java.lang.String object with a value of 2, for example, passed. For parameters that are complex objects, the object can be passed as a parameter and the library will attempt to convert it for transport. When the request is sent to the server, a new instance will be constructed and its properties populated with the values from the original object. Collections and Maps can also be transported. For more information, see Calling Methods with the Java Client Library (page 193).
atg.rest.client.RestRepositoryHelper Class
The methods of the RestRepositoryHelper class allow you to access repository items, execute RQL queries, retrieve individual property values, set property values, create items, and remove items. Each of the methods takes a Nucleus repository path and item descriptor name as its first two arguments, as well as a Map of parameters, which control various aspects of the request. For more information and examples, see Accessing Repository Items with the Java Client Library (page 194). public static RestResult createItem(String pRepositoryPath, String
pItemDescriptorName, Map<String,Object> pParams, RestSession pSession)
Returns the ID of the newly created repository item. public static RestResult createItem(String pRepositoryPath, String
pItemDescriptorName, String pItemId, Map<String,Object> pParams, RestSession pSession)
Returns the ID of the newly created repository item.
184
public static RestResult removeItem(String pRepositoryPath, String

pItemDescriptorName, String pItemId, Map<String,Object> pParams, RestSession pSession)
Returns true if the repository item was successfully removed; otherwise, returns false. public static RestResult getItem(String pRepositoryPath, String pItemDescriptorName,
String pItemId, Map<String,Object> pParams, RestSession pSession)
Returns the contents of the repository item. If any of the properties are references to other items, Collections, arrays, or Maps, returns a REST URL that you can use to access the contents of the specific property. You can create a raw REST request to access the data for the property. For more information, see Creating a Raw REST Request (page 190). public static RestResult getItems(String pRepositoryPath, String
pItemDescriptorName, Map<String,Object> pParams, RestSession pSession)
Returns a series of URLs, one for each item which is being returned. T to control the number of items returned, the atg-rest-index and atg-rest-count parameters can be passed into the pParams argument. public static RestResult executeRQLQuery(String pRepositoryPath, String
pItemDescriptorName, String pRQL, Map<String,Object> pParams, RestSession pSession)
Returns a series of URLs, one for each item which is being returned. To control the number of items returned, the atg-rest-index and atg-rest-count parameters can be passed into the pParams argument. Note: Do not include parameters in the RQL queries that you perform via the REST Web Services. Make sure that all constants are explicitly included in the RQL statements. See information about parameters in RQL queries in the ATG Repository Guide. public static RestResult getPropertyValue(String pRepositoryPath, String
pItemDescriptorName, String pItemId, String pProperty, Map<String,Object> pParams, RestSession pSession)
Returns the value of the requested property. If the property is a Collection, Map, array, or reference to another repository item, returns a URL. public static RestResult setPropertyValue(String pRepositoryPath, String
pItemDescriptorName, String pItemId, String pProperty, Object pValue, Map<String,Object> pParams, RestSession pSession)
Creating a RestSession Object

The Oracle ATG Web Commerce platform REST Web Services calls are executed within the context of an HTTP session. This enables a client application to maintain state across requests and to use login information for security purposes. The RestSession class contains all the logic required for connecting and communicating with an Oracle ATG Web Commerce server. The following code creates a new RestSession object:
RestSession session = RestSession.createSession(host, port, username, password);
Note: You can perform multiple REST Web Services requests during an HTTP session. See information about HTTP sessions and the REST Web Services server in Logging In (page 108).
185
RestSession class properties

The RestSession class includes the following properties. Some are set when the object is created and others can be changed after the object has been constructed:
Property
Hostname
Description The name of the host which the session will or is connected to. Default is localhost. The port number which the session will use. Default is 80. The username the session will use to connect. The password the session will use to connect. The scheme the session will use to connect. Default is HTTP expect for login calls. The web application context root for Oracle ATG Web Commerce platform REST Web Services. Default is /rest.
Port Username Password Scheme
restContextRoot
useInternalProfileForLogin Tells the session object to login as an internal user instead of a profile user. You will probably need to change this property after the RestSession object is
created and before login is called. When connecting to a server that can be accessed only by internal users, this property must be set to true or the login will fail.
useHttpsForLogin httpsPort userId sessionId Encoding inputFormat
Tells the session object to use the HTTPS scheme for login calls. Default is true. The HTTPS port number which the session will use. Default is 443. The userId of the connected user. This value is set after logging in. The session ID of the current session. This value is set after logging in. The encoding to use when encoding parameter values. Default is UTF The default input format that is set on the server. Changing this value has no effect on the server. The default output format that is set on the server. Changing this value has no effect on the server
outputFormat
Starting a REST Session

When you start a REST session, the Oracle ATG Web Commerce platform REST interface sets the session confirmation number, session id, and the default input and output customizers. Start a session by doing one of the following: Log in to the Oracle ATG Web Commerce platform REST interface. See Logging in and Logging Out with the Java Client Library (page 187).
186
Invoke the RestSession.startSession() method. This will start the session but does not authenticate the client for access to secured Oracle ATG Web Commerce components. See Starting a Session Without Logging In (page 189).
Logging in and Logging Out with the Java Client Library

The following code sample is a shell of a simple application. It does nothing more than login and logout. The most interesting portion of the following code sample is the execute method. Note: You can perform multiple REST Web Services requests during an HTTP session. See information about HTTP sessions and the REST Web Services server in Logging In (page 108). The sample first creates a RestSession object. It does this by calling the static RestSession.createSession() method. The parameters to createSession are the hostname, port, username, and password. By default all login calls are issued with HTTPS. If you do not want this functionality, set the value of the useHttpsForLogin flag to false on the session object, as the following sample does. The next section of code calls the login() method on the RestSession object. If the login attempt fails, then a RestClientException is thrown. The last section of code calls the logout() method and concludes the session.
import import import import atg.rest.client.RestClientException; atg.rest.client.RestComponentHelper; atg.rest.client.RestResult; atg.rest.client.RestSession;
import java.io.IOException; public class RestClientSample { private String mUsername = null; private String mPassword = null; private String mHost = "localhost"; private int mPort = 80; private RestSession mSession = null; public RestClientSample() {} protected void parseArguments(String[] pArgs) throws Exception { for (int i = 0; i < pArgs.length; i++) { String arg = pArgs[i]; if (arg.equals("-user")) mUsername = pArgs[i+1]; else if (arg.equals("-password")) mPassword = pArgs[i+1]; else if (arg.equals("-host")) mHost = pArgs[i+1]; else if (arg.equals("-port")) mPort = Integer.parseInt(pArgs[i+1]); } if (isBlank(mUsername)) throw new Exception("Must supply username"); if (isBlank(mPassword)) throw new Exception("Must supply password"); } protected boolean isBlank(String pStr) {
187
return (pStr == null || pStr.length() == 0 || pStr.trim().length() == 0); } protected void println(String s) { System.out.println(s); } protected void println(Throwable t) { t.printStackTrace(System.out); } protected void execute() throws RestClientException { mSession = RestSession.createSession(mHost, mPort, mUsername, mPassword); mSession.setUseHttpsForLogin(false); try { String loginStatus = mSession.login(); if(loginStatus == null || "null".equals(loginStatus)) { mSession = null; System.out.println("Login Failed"); } else { System.out.println("Login Successful"); } } catch (Throwable t) { println(t); } finally { try { if(mSession != null) { mSession.logout(); System.out.println("Logout Successful"); } } catch (RestClientException e) { println(e); } } } /** * @param args */ public static void main(String[] args) { RestClientSample sample = new RestClientSample(); try { sample.parseArguments(args); sample.execute(); } catch (Throwable t) { sample.println(t); } } }
188
Starting a Session Without Logging In

Use the RestSession.startSession() method to start a REST session without authenticating the client. You can log into the REST server after you start the session if that is required. Note: Starting a session without logging in will not give your REST client access to secured Oracle ATG Web Commerce resources. The following sample program starts a REST session using the startSession() method.
import atg.rest.client.RestClientException; import atg.rest.client.RestSession; public class RestClientStartSession { // Use your own hostname and port. private String mHost = "myserver"; private int mPort = 9876; private RestSession mSession = null; public RestClientStartSession() {} protected void execute() throws RestClientException { // Create a RestSession object. Use the constructor that // takes only the REST server host and port. mSession = RestSession.createSession(mHost, mPort); // Invoke the startSession() method. mSession.startSession(); // Verify that the session is started. String sessionid = mSession.getSessionId(); System.out.println("The session ID is: " + sessionid); // perform unsecured operations or login here // forexample: // mSession.login("myusername","mypassword") } public static void main(String[] args) { RestClientStartSession sample = new RestClientStartSession(); try { sample.execute(); } catch (Throwable t) { t.printStackTrace(System.out); } } }
Accessing Data from the Server

Now you can build on the previous example by accessing a Nucleus component property. The example that follows makes a request for all the properties of a Nucleus component using the RestComponentHelper class. This class has several static convenience methods which assist in creating the requests and issuing them to the server. The getComponent() method take the path to a Nucleus component, a map of optional parameters, and the RestSession object and returns a RestResult object.
189
The RestResult object can be used to access the data from the response. The following sample calls readInputStream() to return a String of the response data. In this case, you can assume that the server is using the default output format which is JSON. The string in response data will contain the JSON output. A JSON object is then constructed and output. Another alternative is to simply output responseData, but this sample illustrates how you might use the output. Similarly, if the output format was XML, you could create an XML document object using dom4j. The finally block includes a call to close the result. Doing this will release the underlying connection resources. If this call is omitted, the next call to the server using the same RestSession object will close the result.
protected void execute() throws RestClientException { RestResult result = null; mSession = RestSession.createSession(mHost, mPort, mUsername, mPassword); mSession.setUseHttpsForLogin(false); try { mSession.login(); println("Login Successful"); result = RestComponentHelper.getComponent("/atg/dynamo/Configuration", null, mSession); String responseData = result.readInputStream(); if (responseData != null) { JSONObject json = new JSONObject(responseData); println(json.toString()); } } catch (Throwable t) { println(t); } finally { if (result != null) result.close(); try { mSession.logout(); println("Logout Successful"); } catch (RestClientException e) { println(e); } } }
Creating a Raw REST Request

The RestComponentHelper and RestRepositoryHelper classes might not support every type of request you want to issue to the server. If this is the case, you can issue a request using the createHttpRequest() method of the RestSession class. There are two versions of this method:
public RestResult createHttpRequest(String pURL, Map<String,Object> pParams, String pMethodType)
190
public RestResult createHttpRequest(String pURL, Map<String,Object> pParams, Object[] pArguments, String pMethodType)
The following table describes the arguments for each version of this method.
Argument
pURL
Description The URL to request, formatted as http://hostname:port/uri The pURL argument must be an absolute URL, including the hostname (and port, if it is not 80). The RestSession class includes a convenience method called getHostString() which returns a string containing the scheme, host, and port number. The caller can then append the remainder of the URL and pass the resulting string as the first argument to this method.
pParams
A Map of parameters to submit along with the request. This argument is the same as it would have been if you made the request using either of the helper classes. It contains parameters which can control certain aspects of the request.
pArguments
An array of Objects which contain the method parameter values. Use this argument only for method calls. The value is the same as it would be if calling the executeMethod() method on the RestComponentHelper class.
pMethodType
The HTTP method for the request: GET, POST, PUT, or DELETE. The atg.rest.client.RestConstants class contains constant values for these strings. In short, GET should be used when retrieving data, POST should be used when calling methods, PUT should be used when setting properties, and DELETE is used for deleting repository items. DELETE is not used when interacting with Nucleus components.
Handling Results
createHttpRequest() and all the helper class methods return a RestResult object that allows
access to various parts of the response. The most interesting and useful method on the RestResult is readInputStream(). This is a convenience method which will return the response data into a String
public String readInputStream() throws IOException
After calling this method the String object which is returned will contain the JSON or XML with the content which was requested. The REST module uses the org.json.jar library and the dom4j XML library internally. You can also use these libraries, or comparable libraries, in your applications.
191
If the response data is large, you can access the input stream directly by calling getInputStream() on the RestResult. Other useful methods on the RestResult object are getResponseCode() and getResponseMessage(). These return the responses response code and message, respectively. For more information, see HTTP Status Codes (page 125). The Java client library uses the java.net.HttpURLConnection class to communicate with servers. To access any functionality that the RestResult does not expose, call the getConnection() method to return the underlying HttpURLConnection object. When you are finished with the RestResult object, it is good practice to call the close() method. This releases any resources that the HttpURLConnection might hold. If the connection is not closed, the next request to the server will close the HttpURLConnection.
Accessing Components with the Java Client Library

This section explains how to work with components using the Java client library for the Oracle ATG Web Commerce platform REST Web Services.
Getting Component Data

The getComponent() method of the RestComponentHelper class returns a data stream that contains a representation of a component. The following code sample returns the Configuration component:
RestResult result = RestComponentHelper.getComponent("/atg/dynamo/Configuration", null, mSession)
Getting and Setting Property Values

The getPropertyValue() method of the RestComponentHelper class returns a data stream that contains the value of the specified property. The following code sample gets the value of the property httpPort from the Configuration component.
RestResult result = RestComponentHelper.getPropertyValue("/atg/dynamo/Configuration", "httpPort", params, session)
Use the RestComponentHelper.setPropertyValue() method to set property values on Nucleus components. The following code sample sets the value of the Configuration component property httpPort to 8580.
RestResult result = RestComponentHelper.setPropertyValue("/atg/dynamo/Configuration", "httpPort", "8580", params, session)
192
Calling Methods with the Java Client Library

You can use the Oracle ATG Web Commerce platform REST Web Services to call public methods on Nucleus components. If a method is overloaded, then the server will attempt to determine which method to call by looking at the number of arguments supplied. It is also possible to supply a method signature as a parameter to the RestComponentHelper.executeMethod() method. Supplying the atg-rest-method parameter allows you to specify the exact method to be called. The value of the parameter should be the Java method signature of the method to call. You can find the method signature for a method by using the javap command, which disassembles a class file. (The javap command is part of the JDK.) Depending on the return type of the method, the output will vary. If the output is an object, then it will return a JSON or XML stream which contains the values of all the properties in the object. If it is a simple type like an int or a String, it will return the value. The identifier for the return type is atgResponse.
Passing Parameters to Methods

If you use the Java or ActionScript client libraries that ship with the Oracle ATG Web Commerce platform REST Web Services, passing parameters to methods is as simple as supplying the Objects in the pArguments argument for the RestComponentHelper.executeMethod() method. For more information, see ATG Client Libraries (page 183). If one of the parameters is a simple type, then it should be wrapped in an object. For example, an int will become a java.lang.Integer, a boolean becomes a java.lang.Boolean, and so on. When you pass collections, Maps, and arrays as parameters, the client library attempts to convert those types. Date, Time, and Timestamp objects can also be passed, as shown in the following sample.
RestResult result = RestComponentHelper.executeMethod("/some/Component", "aMethod", new Object[] {1,2,3,4.4,5.5,true,'a',0xa}, null, session)
In order to pass repository items, use a preformatted string that takes the format of
repository Nucleus path:item descriptor name:item id
For example:
/atg/commerce/catalog/ProductCatalog:product:prod12345
When you reference a repository item this way, the server performs a lookup and uses the item as the method argument. For example:
RestResult result = RestComponentHelper.executeMethod("/some/Component", "aMethod", new Object[] {"/atg/commerce/catalog/ProductCatalog:product:prod12345"}, null, session)
If a method takes a GenericService as an argument, simply passing the Nucleus path as a string will cause the server to lookup the Nucleus component and use it as the method argument. For example:
RestResult result = RestComponentHelper.executeMethod("/some/Component", "aMethod", new Object[] {"/atg/dynamo/Configuration"}, null, session)
193
If passing a complex Java object, attempt to add the object to the pArguments argument and call the method. In most cases, the argument will not need to be transformed before it is transported to the server. The client library will make an attempt at converting the object for you.
MyObject myObject = new MyObject(); RestResult result = RestComponentHelper.executeMethod("/some/Component", "aMethod", new Object[] {myObject}, null, session)
Calling Handler Methods

Form handlers use special handler methods for linking form elements with Nucleus components. One of the more powerful features in the Oracle ATG Web Commerce platform REST Web Services module is the ability to call handler methods. If you have existing JSP-based applications, all the functionality which has previously been exposed in those applications can be reused with REST based applications. Use RestComponentHelper.executeMethod() to call handler methods. Keep the following in mind when calling a handler method The method name, the second argument in the executeMethod() method, should not contain the handle prefix. For example, to call the handleCreate method, it should be specified simply as create in the pMethodName argument. The pArguments parameter should always be null when you call a handler method. The following code sample calls the handleCreate method on a specified form handler:
RestResult result = RestComponentHelper.executeMethod("/some/FormHandler", "create", null, null, session)
As long as a form handler does not submit a redirect, the execution would be similar to a regular method call. For those form handler methods which do redirect, the redirect will be intercepted and returned back to the client as an exception.
Passing Parameters to Form Handlers

Form handler parameters which need to be supplied should be added to the params argument. In a JSP page these parameters would be the input tags in a JSP form. The following example calls the handleCreate() method on a form handler. The inputs to the form handler are a first and last name.
Map<String,String> params = new HashMap<String,String>(); params.put("firstName", "Andy"); params.put("lastName", "Jones"); RestResult result = RestComponentHelper.executeMethod("/some/FormHandler", "create", null, params, session);
Accessing Repository Items with the Java Client Library

The Oracle ATG Web Commerce platform REST Web Services RestRepositoryHelper class exposes methods that perform basic Repository operations.
194
Getting Repository Items with the Java Client Library

The getItem() method of the RestRepositoryHelper class returns a data stream that contains all the property values of a repository item. The following code sample returns an array of URLs. Issuing a request using the RestSession.createHttpRequest() method returns the property values of the requested item.
RestResult result = RestRepositoryHelper.getItem("/atg/commerce/catalog/ ProductCatalog", "product", productId, params, session)
The getItems() method retrieves multiple repository items of the same type in a single call. The following code sample returns an array of URLs:
RestResult result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ ProductCatalog", "product", params, session)
When a getItems() call returns many items, you can control the number of items returned with the atgrest-index and atg-rest-count parameters. The atg-rest-index parameter tells the server which item to return first. The atg-rest-count parameter tells the server how many items past the index item to return. In the following code sample, the first query, with an index of 0 and a count of 10, retrieves 10 items at a time. The next query has an index of 10 and a count of 10, third, index of 20 and count of 10, and so on.
Map<String,String> params = new HashMap<String,String>(); params.put(RestConstants.COUNT, 10); params.put(RestConstants.INDEX, 0); RestResult result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ ProductCatalog", "product", params, session); params.put(RestConstants.INDEX, 10); result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCatalog", "product", params, session); params.put(RestConstants.INDEX, 20); result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCatalog", "product", params, session);
Repository IDs
Each repository item has a unique identifier, called a repository ID. Depending on the repositorys configuration, the repository ID might not be exposed as a property of the repository item. However, when a repository item is returned with a Rest RepositoryHelper method, you can reliably retrieve its repositoryID by getting the value of the repositoryId property.
Adding Repository Items

Create a repository item by calling the RestRepositoryHelper.createItem() method. You can supply a repository ID for the newly created item or you can allow the server to generate a repository ID for you.
195
A createItem() call returns a data stream that contains all the properties of the created item. This is the same data stream that is returned when you call RestRepositoryHelper.getItem(). The following code sample adds a repository item and allows the server to generate the repository ID:
RestResult result = RestRepositoryHelper.createItem("/atg/commerce/catalog/ ProductCatalog", "product", params, session);
The following code sample adds a repository item and specifies the value of myProductId-12345 as the repository ID:
RestResult result = RestRepositoryHelper.createItem("/atg/commerce/catalog/ ProductCatalog", "product", "myProductId-12345", params, session);
Deleting Repository Items

Remove a repository item by calling the RestRepositoryHelper.removeItem() method. A removeItem() call returns a data stream that contains the string true if the item was removed. If the item was not removed, the call throws an exception. The following sample removes a repository item:
RestResult result = RestRepositoryHelper.removeItem("/atg/commerce/catalog/ ProductCatalog", "product", "myProductId-12345", params, session);
Getting Repository Item Properties with the Java Client

The getPropertyValue() method of the RestRepositoryHelper class returns a data stream that contains the value of the specified property. The following sample gets the property value displayName from the product repository item.
RestResult result = RestRepositoryHelper.getPropertyValue("/atg/commerce/catalog/ ProductCatalog", "product", "prod12345", "displayName", params, session);
Setting Repository Item Properties with the Java Client

The setPropertyValue() method of the RestRepositoryHelper class sets the value of the specified property. The following sample sets the property displayName to the string My Modified Display Name.
RestResult result = RestRepositoryHelper.setPropertyValue("/atg/commerce/catalog/ ProductCatalog", "product", "prod12345", "displayName", "My Modified Display Name", params, session);
196
Performing Queries for Repository Items

Performing queries for repository items using RQL is similar to retrieving them with getItems(), but querying provides for more control over the items included in the results. Use the RestRepositoryHelper.executeRQLQuery() method to execute and RQL query. To request a range of items, use the atg-rest-index and atg-rest-count parameters with the executeRQLQuery() method, just as youd use them with getItems(). See Getting Repository Items (page 35) for more information. In the following example, the INDEX and COUNT keywords in the RQL language are used instead of the atg-restindex and atg-rest-count parameters.
Map<String,String> params = new HashMap<String,String>(); params.put(RestConstants.COUNT, 10); params.put(RestConstants.INDEX, 0); RestResult result = RestRepositoryHelper.executeRQLQuery("/atg/commerce/catalog/ ProductCatalog", "product", "age >= 30", params, session); params.put(RestConstants.INDEX, 10); result = RestRepositoryHelper.executeRQLQuery("/atg/commerce/catalog/ProductCatalog", "product", "age >= 30", params, session);
params.put(RestConstants.INDEX, 20); result = RestRepositoryHelper.executeRQLQuery("/atg/commerce/catalog/ProductCatalog", "product", "age >= 30", params, session);
Using the Java Client in Android Applications

The Java REST client includes the class AndroidIntrospectorService which implements atg.rest.client.beans.IntrospectorService. This class is a replacement for the java.beans.Introspector class, which does not work on Android devices. To use the Java REST client in an Android application, include the following file in the applications Java class path.
META-INF/services/atg.rest.client.beans.IntrospectorService
Include the following content in the file:

atg.rest.client.beans.AndroidIntrospectorService
ActionScript Client Library

ActionScript is the programming language for the Adobe Flash Player run-time environment. This library is useful for client applications written in Adobe Flash or Adobe Flex.
197
Note: The Oracle ATG Web Commerce platform REST Web Services were tested with ActionScript 3. The ActionScript client library is nearly identical in structure to the Java client library. The main difference between the two libraries is the way they handle results: The Java client library uses the RestResult class to handle results. The ActionScript library does not include a RestResult class; instead, it handles results using a callback mechanism. Therefore, helper class methods and the createHttpRequest() method for the ActionScript client library take a result handler and fault/error handler functions as arguments. The following code sample illustrates how the ActionScript client library handles results.
public function getPropertyValue():void { RestComponentHelper.getPropertyValue("/atg/dynamo/Configuration", "httpPort", null, session, handleResult, handleFault); // get the httpPort property from the Configuration component } public function handleResult(pEvent:Event):void { var xml:XML = new XML(pEvent.target.data); // create an XML object populateGridWithXML(xml); // populate the control with the XML output } public function handleFault(pEvent:Event):void { Alert.show("Fault"); // display an error dialog }
atg.rest.client.RestComponentHelper
The RestComponentHelper class simplifies Nucleus requests. The RestComponentHelper methods are written in ActionScript as follows. For details about individual class methods, refer to the Java Client Library (page 183) section.
public static function getComponent(pComponentPath:String, pParams:Array, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void public static function getPropertyValue(pComponentPath:String, pProperty:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void public static function setPropertyValue(pComponentPath:String, pProperty:String, pValue:Object, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void public static function executeMethod(pComponentPath:String, pMethodName:String, pArguments:Array, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void
198
atg.rest.client.RestRepositoryHelper
The RestRepositoryHelper class simplifies repository requests. The RestRepositoryHelper class methods are written in ActionScript as follows. For details about individual class methods, refer to the Java Client Library (page 183) section.
public static function getItem(pRepositoryPath:String, pItemDescriptorName:String, pItemId:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void public static function getItems(pRepositoryPath:String, pItemDescriptorName:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void public static function executeRQLQuery(pRepositoryPath:String, pItemDescriptorName:String, pRQL:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void public static function getPropertyValue(pRepositoryPath:String, pItemDescriptorName:String, pItemId:String, pProperty:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void public static function setPropertyValue(pRepositoryPath:String, pItemDescriptorName:String, pItemId:String, pProperty:String, pValue:Object, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void public static function createItem(pRepositoryPath:String, pItemDescriptorName:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void public static function createItemWithId(pRepositoryPath:String, pItemDescriptorName:String, pItemId:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void public static function removeItem(pRepositoryPath:String, pItemDescriptorName:String, pItemId:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void
Calling Methods with ActionScript

The ActionScript client librarys RestClientHelper class includes the following helper methods, which convert arrays, Lists, and Objects to MultiValue objects:
public static function convertArrayToMultivalue(pValue:Array, pMultiValueType:String, pComponentType:String, pFormat:String, pSession:RestSession):String public static function convertIListToMultivalue(pValue:IList, pMultiValueType:String, pComponentType:String, pFormat:String, pSession:RestSession):String
199
public static function convertObjectToMultivalue(pValue:Object, pMultiValueType:String, pKeyType:String, pValueType:String, pFormat:String, pSession:RestSession):String
The following table describes the arguments for each of these methods.
Argument
pMultiValueType
Description The absolute path of a Java class, such as java.util.ArrayList. Be sure to specify a valid class name and not an interface name. The class type of the component to instantiate for each element in the multivalve type. For example, an array of integers in ActionScript could be converted to an ArrayList of java.lang.Integer objects. The servers input format type. This can be retrieved from the session objects inputFormat property. ActionScript objects act as associative arrays (similar to java Maps), the convertObjectToMultivalue() method takes a key type and value type. These arguments are similar to pComponentType and are absolute names of Java classes to use for the key and value objects in the Java Map.
pComponentType
pFormat
pKeyType pValueType
Similar to the Java client library, passing arguments to methods is generally straightforward. For primitive types, just add them to the pArguments array.
var result:RestResult = RestComponentHelper.executeMethod("/some/Component", "aMethod", [1,2,3,4.4,5.5,true,'a',0xa], null, session, handleResult, handleFault)
To pass a reference to a repository item, use the format

<repository path:item descriptor name:item id>
For example:
var result:RestResultRestComponentHelper.executeMethod("/some/Component", "aMethod", ["/atg/commerce/catalog/ProductCatalog:product:prod12345"], null, session, handleResult, handleFault)
To pass a reference to a Nucleus component, pass the Nucleus component path. For example:
var result:RestResultRestComponentHelper.executeMethod("/some/Component", "aMethod", ["/atg/dynamo/Configuration"], null, session, handleResult, handleFault)
The following example is a call to a method which takes a repository item array and a GenericService array.
<programlisting>
200
var result:RestResultRestComponentHelper.executeMethod("/some/Component", "aMethod", [["/atg/commerce/catalog/ProductCatalog:product:prod12345", "/atg/commerce/catalog/ProductCatalog:product:prod67890"], ["/atg/dynamo/Configuration","/atg/dynamo/Configuration"]], null, session, handleResult, handleFault)
As mentioned above, arrays, ILists, and Objects must be converted before being passed to the server. The following example demonstrate passing an array using the helper methods in the RestClientUtils class.
var arrayCollection:ArrayCollection = new ArrayCollection(["abc","def"]); var result:RestResultRestComponentHelper.executeMethod("/some/Component", "aMethod", [RestClientUtils.convertIListToMultivalue(arrayCollection, "java.util.ArrayList", "java.lang.String", RestConstants.JSON, session)], null, session, handleResult, handleFault);
The following example, which calls executeMethod(), produces the same result as the previous example:
var result:RestResultRestComponentHelper.executeMethod("/some/Component", "aMethod", ["java.util.ArrayList:java.lang.String:[\"abc\",\"def\"]"], null, session, handleResult, handleFault)
The following examples use the helper methods in the RestClientUtils class.
var result:RestResultRestComponentHelper.executeMethod("/some/Component", "aMethod", [RestClientUtils.convertArrayToMultivalue(["abc","def"], "java.util.HashSet", "java.lang.String", RestConstants.JSON, session)], null, session, handleResult, handleFault) var obj:Object = new Object(); obj["abc"] = 123; obj["def"] = 456; var result:RestResultRestComponentHelper.executeMethod("/some/Component", "aMethod", [RestClientUtils.convertObjectToMultivalue(obj, "java.util.HashMap", "java.lang.String", "java.lang.Integer", RestConstants.JSON, session)], null, session, handleResult, handleFault)
Formatting Input with ActionScript

The option to use JSON or XML with ActionScript is available. In order to use JSON you will need to include the Adobe corelib library. This library contains functionality to encode and decode JSON streams. In the example below, the pEvent object is of type Event and is supplied by the Flash runtime when the handler method is called. pEvent.target.data contains the response data stream. This stream is decoded into an Object. The sample iterates through the properties constructing an object for each name/value pair and then adds it to an ArrayCollection object.
var json:Object = JSON.decode(pEvent.target.data); for (var propName:String in json)
201
arrayCollection.addItem({name: propName, value: json[propName]});
The following sample uses XML input. Note that you could also take advantage of the ECMAScript for XML functionality once the XML object is created. The following sample does not use that approach, though it is an option.
var xml:XML = new XML(pEvent.target.data); var xmlList:XMLList = pXML.elements(); if (xmlList.length() == 0) xmlList = new XMLList(pXML); var count:int = 0; for each(var item:XML in xmlList) { if (item.name() != "element") array.addItem({name: item.name(), value: item.text()}); else if (item.hasComplexContent()) { var elementList:XMLList = item.child("element"); if (elementList != null && elementList.length() > 0) { var count2:int = 0; for each (var el:XML in elementList) array.addItem({name: count2++, value: el.text()}); } else array.addItem({name: item.key.text(), value: item.value.text()}); } else array.addItem({name: count++, value: item.text()}); }
202
Index
Symbols
.NET clients ATGWS.dll, 60 before calling Web Services, 57 calling Web Services, 55 client stubs, 56 security, 55 session sharing, 44, 56 transactions, 56 Web Service call examples, 59, 59
A
about ATG Web Services, 43, 55 acceptJSONInput, 177 accessing ATG Web Services from .NET clients, 55 accessing ATG Web Services from Java clients, 43 ActionScript client library REST Web Services, 197 add-item tag, 90 addItem operations, 81 AddService, 37 data validation, 37 allowAccessForUnsecuredRepository, 178 appendMultiValuesByDefault, 178 arg1 functional parameter, 115 asynchronous requests, 128 ATG client libraries REST Web Services, 183 ATG Web Services, 3, 15 atg-rest-form-tag-priorities, 148 atg-rest-null, 124 atg-rest-output, 126 atg-rest-property-filters, 169 atg-rest-return-form-handler-exceptions, 146 atg-rest-return-form-handler-properties, 147 atg-rest-show-rest-paths, 129 atg-rest-transient, 161 atg-rest-user-input, 128 atg.adapter.integrations.ChangedPropertyBean, 77 atg.adapter.integrations.IntegrationRepository, 74
atg.adapter.integrations.IntegrationRepositoryItem, 77 atg.adapter.integrations.IntegrationRepositoryItemDescriptor, 76 atg.adapter.integrations.IntegrationRepositoryView , 78 Atg.DotNet.WebService API, 60 Atg.DotNet.WebService.ComplexType, 64 Atg.DotNet.WebService.NoSuchPropertyException, 64 Atg.DotNet.WebService.Property, 63 Atg.DotNet.WebService.RepositoryItem, 62 Atg.DotNet.WebService.RepositoryItemRef, 63 Atg.DotNet.WebService.RepositoryItemSerializationException, 65 atg.integrations.BaseCommand, 97 atg.integrations.BaseCommandHandler, 97 atg.integrations.Command interface, 95 atg.integrations.CommandHandler interface, 96 atg.integrations.CommandResults, 97 atg.integrations.MapRPCDroplet, 98 atg.repository.databinding.MappingRepositoryItem, 77 atg.repository.RepositoryService, 25 atg.repository.xml.AddService, 37 atg.repository.xml.GetService, 35 atg.repository.xml.RemoveService, 40 atg.repository.xml.UpdateService, 38 atg.repository.xml.XMLSchemaManager, 34 ATGWS.dll client stubs for .NET, 56, 60 deserializing RepositoryItems, 56 installing, 57 serializing RepositoryItems, 56 Axis calling Web Services using, 47
C
client stubs for .NET, 56 client stubs for Java clients (see static Web Service calls) command operations addItem, 81 executeQuery, 79 getItem, 80 Integration Repository, 79 removeItem, 81 updateItem, 80 CommandHandlers, 96 CommandResults, 97 commands, 96 executing, 96 executing in pages, 98 invoking, 96 component properties getting, 139 in REST Web Services, 139 setting, 140
Index
203
components REST path for, 105 configuration of the REST Web Services server, 173 Content-Type, 117 control parameters, 112 CookieContainer, 44, 44, 45, 56 .Net client example, 59 Java client example, 49, 50 curl command-line utility, 106 custom Web Services, 5
filtering templates, 168 filteringConfiguration.xml, 165 form handlers form value priority, 148 invoking with the REST Web Services, 145 returning exceptions, 146 returning properties, 147 submitting form values, 146 form values priority, 148 functional parameters, 115 positional, 115
D
data binding repository to XML (see repository to XML data binding) data validation, 37, 38 date format REST, 135 date format in REST input, 124 default-acl, 180 defaultOutputCustomizer, 126, 173 definition files Integration Repository, 72, 87 derived properties updating, 80 derived-properties tag, 90 deserializing content on the client side, 51, 60 dot Net clients (see .NET clients) DTDs Integration Repository, 91 repository to XML mapping files, 28 dynamic Web Service calls, 50 distinction from static calls, 47 limitations, 47 Dynamo Administration UI Web Service creation wizard, 7, 19 Web Service registry, 16 Web Service security manager, 15
G
generateXMLSchema utility, 33 get-item tag, 89 getItem operations, 80 GetService, 35
H
HTTP status codes, 125 HTTP methods for REST Web Services, 107 HTTP requests, 104
I
input values REST Web Services, 118 Installing ATGWS.dll, 57 Integration Data repository, 82 cleaning up, 83 Integration Repository, 69 APIs, 73 architecture, 69 command operations, 79 definition files, 72, 87 DTD, 91 examples, 84 operations, 69 persistent cache, 82 queries, 78 setting up, 72 IntegrationRepository component, 73, 74 IntegrationRepositoryView, 69 internal users logging into REST Web Services server, 110 item-descriptor tag, 87
E
enableFormatDateOutput, 174, 176 errors, 135 exceptions, 135 returning for form handlers, 146 executeQuery operations, 79 expand attribute, 172 external users logging into REST Web Services server, 109
F
filter depth specifying default, 167 specifying for one request, 169
J
Java classes controlling property expansion for, 171
204
Index
Java client library REST Web Services, 183 Java clients before calling Web Services, 45 calling Web Services, 43 CookieContainer, 44, 45, 49, 50 deserializing content, 51 dynamic Web Service calls, 50 security, 44 serializing content, 51 starting REST session, 189 static Web Service calls, 48, 50 transactions, 44 two ways to call Web Services, 47 JAX-RPC, 6 deployment descriptor, 13 mapping file, 13 JMS Web Services, 19 MessageImporter component, 20 Patch Bay configuration, 20 JSON markup for parameters, 118 JSON output, 127 JSPs invoking via REST Web Services, 149
XML Schema, 36 Nucleus component Web Services, 8 Nucleus components REST, 101 null values in REST input, 124
O
object values for properties, 121 nested multiple value objects, 122 operations repository items, 69 output markup REST Web Services, 126
P
parameters control, 112 functional, 115 JSON markup, 118 message body, 116 URL query string markup, 118 XML markup, 117 Patch Bay configuration for JMS Web Services, 20 persistent cache (see Integration Data repository) positional parameters, 115 POST method handling as other methods, 108 priority property filtering for REST requests, 172 properties returning for form handlers, 147 property aliasing, 170 property filtering, 165 propertyElementNameSeparator, 34
L
logging in as internal user, 110 external users, 109 to the REST Web Services server, 108 logging out of the REST Web Services server, 112
M
mapping files DTD, 28 example, 29 repository to XML data binding, 28 MappingRepositoryItem, 77 maxDepthAllowed, 173 message body parameters, 116 Content-Type, 117 MessageImporter component, 20 methods invoking with the REST Web Services, 143 multiple values in REST Web Services output, 129 JSON input for, 121 replacing in a repository item property, 121
Q
queries executeQuery operation, 79 Integration Repository, 78 query string parameters, 116 query tag, 88
R
Remote Procedure Calls, 95 APIs, 95 exception handling, 98 remove-item tag, 90 removeItem operations, 81 RemoveService, 40 removing repository items, 40 repositories
N
namespaces
Index
205
REST path for, 105 repository item properties appending values, 120 replacing multiple values, 121 retrieving, 157 repository items adding, 160 deleting, 163 generating from XML documents, 37 listing, 155 REST Web Services, 155 retrieving, 156 setting properties, 162 transforming into XML documents, 35 transient, 161 repository to XML data binding, 27 mapping files, 28 XML Schemas, 32 repository to XML mapping files DTD, 28 example, 29 repository Web Services, 23 limitations, 24 Repository XML schema generating, 52 mapping file, 51 RepositoryItems deserializing, 51, 60 serializing, 51, 60 Web Service calls from Java clients, 44, 56 XML schema for Web Service calls, 49 RepositoryService class, 25 REST Nucleus components, 101 REST module Starting, 104 REST property filtering filtering priority, 172 filtering templates, 168 REST sessions starting, 189 REST Web Services, 103 ATG client libraries, 106, 183 client software, 106 configuring the server, 173 control parameters, 112 functional parameters, 115 identifying a response, 128 input values, 118 invoking JSPs, 149 output markup, 126 property aliasing, 170 property filtering, 165
repository items, 155 returned data, 126 security, 179 return depth, 134 return values controlling property expansion, 171 returnFormHandlerExceptionsByDefault, 174 returnFormHandlerPropertiesByDefault, 174 RPCs (see Remote Procedure Calls) RQL queries, 158
S
Scenario Manager receiving messages from JMS Web Services, 21 SchemaManager component, 34 security REST Web Services, 179 Serializing content on the client side, 51, 60 service endpoint interface, 9 service interface class, 9 session identifiers for REST Web Services session, 108 session sharing example, 49, 50, 59 sessions sharing (.NET clients), 44, 56 showRestPaths, 175, 177 startSession(), 189 static Web Service calls, 48 creating and compiling stubs, 49 creating and compiling the client, 49 distinction from dynamic calls, 47 WSDL, 49, 49 status codes, HTTP, 125 stubs (see client stubs) (see client stubs for .NET)
T
templates filtering, 168 time zone in REST dates, 135
U
updateItem operations, 80 derived properties, 80 UpdateService, 38 data validation, 38 updating repository items from XML documents, 38 URL parameters, 116 URL query string markup for parameters, 118 URLs
206
Index
REST Web Services, 104
repository to XML data binding, 32
V
validating data AddService, 37 UpdateService, 38
W
Web Service security, 13 NucleusSecurityManager, 14 NucleusSecurityRepository, 14 Web Services Administration UI, 7, 19, 23 ATG Web Services, 3, 15 before calling from .NET, 57 before calling from Java clients, 45 calling from .NET clients, 55, 58 calling from Java clients, 43, 47, 50 client stubs for .NET, 56 custom Web Services, 5 deploying, 15 generating, 6 infrastructure, 1 JMS messages, 19 limitations, 6 managing, 16 naming restrictions, 9 Nucleus component methods, 8 overview, 5 repository items, 23 REST, 103 runtime classes, 13 security, 6, 44, 44, 44, 55, 56, 56, 56 transactions, 44, 56 wizard, 7, 19 web.xml files, 11 WSDL documents, 10
X
XML documents generating from repository items, 35 transforming into repository items, 37 updating repository items, 38 XML markup for parameters, 117 XML output, 127 XML SchemaManager component, 34 XML Schemas for Web Services, 51 generation utility, 33 itemRef attribute, 34 namespace, 36 references to other repository items, 34
Index
207
208
Index

ATGWSFrame Guide

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ATGWSFrame Guide

Uploaded by

Copyright:

Available Formats

Version 10.1.

Web Services and Integration Framework Guide

Oracle ATG One Main Street Cambridge, MA 02142 USA

ATG Web Services and Integration Framework Guide

ATG Web Services and Integration Framework Guide

ATG Web Services and Integration Framework Guide

ATG Web Services and Integration Framework Guide

ATG Web Services and Integration Framework Guide

ATG Web Services and Integration Framework Guide

ATG Web Services and Integration Framework Guide

Part I. Creating and Using Web Services in the ATG Platform

ATG Web Services

Web Application Generic Repository Services

1 ATG Web Services

Web Application Order

1 ATG Web Services

Creating Custom Web Services

Overview of ATG Web Services Support

2 Creating Custom Web Services

Automatic Generation of Web Services

Session and Security Support

2 Creating Custom Web Services

Web Service Creation Wizard

Using the Wizard

2 Creating Custom Web Services

2 Creating Custom Web Services

Anatomy of a Web Service

Service Endpoint Interface and Implementation Class

2 Creating Custom Web Services

2 Creating Custom Web Services

2 Creating Custom Web Services

Handling Imported WSDL Documents

Web Service Registrar

2 Creating Custom Web Services

Other Elements of web.xml

JAX-RPC Deployment Descriptor and Mapping Files

JSR 109 Compliant EAR File

Web Service Security

2 Creating Custom Web Services

2 Creating Custom Web Services

Creating and Editing Security Configurations

Deploying Web Services

runAssembler -add-ear-file WS.ear MyApp.ear -m MyApp DSS

2 Creating Custom Web Services

Managing Web Services

2 Creating Custom Web Services

2 Creating Custom Web Services

2 Creating Custom Web Services

Creating JMS Web Services

Using the JMS Message Web Service Wizard

3 Creating JMS Web Services

Structure of a JMS Web Service

Patch Bay Configuration

3 Creating JMS Web Services

3 Creating JMS Web Services

3 Creating JMS Web Services

Creating Repository Web Services

Using the Repository Web Service Wizard

4 Creating Repository Web Services

Repository Web Service Limitations

4 Creating Repository Web Services

Modifying Repository Web Services