ATG-Web Services and Integration Framework Guide

Version 9.4

Web Services and Integration Framework Guide

Oracle ATG

One Main Street

Cambridge, MA 02142

USA

ATG Web Services and Integration Framework Guide

Product version: 9.4

Release date: 10-31-11

Document identifier: WebServicesGuide1302201327

Copyright 1997, 2011 Oracle and/or its affiliates. All rights reserved.

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 RIGHTS

Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial

computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific

supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and

license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the

additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle

Parkway, Redwood City, CA 94065.

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.

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 licensed through X/Open Company, Ltd.

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.

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/us/

corporate/accessibility/index.html.

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/support/

contact.html or visit http://www.oracle.com/accessibility/support.html if you are hearing impaired.

ATG Web Services and Integration Framework Guide iii

Table of Contents

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

1. 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

2. Creating JMS Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Using the JMS Message Web Service Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Structure of a JMS Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Patch Bay Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3. 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

4. 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

PropertyElementNameSeparator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Item References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Repository Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Getting Repository Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Adding Repository Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Updating Repository Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Removing Repository Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

5. Accessing ATG Web Services from Java Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

About ATG Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Sharing Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

RepositoryItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

iv ATG Web Services and Integration Framework Guide

Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Writing a CookieContainer Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Calling ATG Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Creating a Call Using a Client Stub (Static) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Creating a Call Using the Dynamic Invocation Interface (Dynamic) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Creating a Serializer and Deserializer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Creating a Mapping File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Generating an XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

6. Accessing ATG Web Services from .NET Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

About Web Services in the ATG Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Session Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Client Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Web Services that Access RepositoryItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Installing ATGWS.dll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Calling ATG Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Accessing an ATG Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Accessing a Custom ATG Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Sample Web Service Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Using the Atg.DotNet.WebService API to Serialize and Deserialize RepositoryItems . . . . . . . . . . . . . . . . . 58

RepositoryItem Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Property Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

RepositoryItemRef Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Complex Type Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

NoSuchPropertyException Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

RepositoryItemSerializer Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

RepositoryItemSerializationException Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

II. Integration Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

7. Integration Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Integration Approaches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Remote Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Remote then Local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Local then Remote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Local Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Setting Up an Integration Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Defining an Integration Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Integration Repository APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

IntegrationRepository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

IntegrationRepositoryItemDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

IntegrationRepositoryItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

ChangedPropertyBean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

atg.repository.databinding.MappingRepositoryItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

IntegrationRepositoryView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Command Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

executeQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

getItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

updateItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

addItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

removeItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

ATG Web Services and Integration Framework Guide v

Persistent Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Cleaning up the Persistent Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Configuration Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Configuring the Remote-Only Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Configuring the Remote-then-Local Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Configuring the Local-then-Remote Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Integration Repository Definition File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

integration-repository-template tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

header tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

item-descriptor tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

item-descriptor Child Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

integration-repository Document Type Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

8. Remote Procedure Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

RPC API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Command Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

CommandHandler Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

CommandResult Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Implementing the RPC API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Executing Commands in Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

III. ATG Platform REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

9. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Starting the ATG Server with the REST Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Setting the Default ACL for REST Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Configuring the Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Creating Simple Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

10. Client Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Creating Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Creating a RestSession Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Logging in and Logging Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Accessing Data from the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Creating a Raw REST Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Handling Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

ActionScript Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

atg.rest.client.RestComponentHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

atg.rest.client.RestRepositoryHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

11. Working with Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

A Note about Output Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

A Note about Nucleus Component Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Getting Component Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Getting and Setting Property Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

12. Calling Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Passing Parameters to Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Calling Handler Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Passing Parameters to Form Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Calling Methods with ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

13. Working with Repository Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

About Output Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

About Repository Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Getting Repository Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Repository IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Adding Repository Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

vi ATG Web Services and Integration Framework Guide

Deleting Repository Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Getting Repository Item Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Setting Repository Item Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Performing Queries for Repository Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

14. Input and Output Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Parsing Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

JSON Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

XML Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Formatting Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Formatting Input with ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

15. Property Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Property Aliasing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

16. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Global Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Component Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Property and Method Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Securing Groups of Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

17. Control Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

18. HTTP Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Part I. Creating and Using Web

Services in the ATG PlatformA 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 ATG 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 ATG 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 ATG 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 ATG 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 41)

Accessing ATG Web Services from .NET Clients (page 53)

ATG Web Services

In addition to any Web services you create, the ATG 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 Web Application Web Services

DAS.WebServices

For more information about

these Web services, see the

ATG Repository Guide.

Generic Repository

Services

- getRepositoryItem- performRQLQuery- performRQLCountQuery

User Session - loginUser- logoutUser- getProfileId- setLocale- setContactInfo- setPassword- getProfile- createUser- updateUser- getPasswordHashKey- getPasswordHashAlgorithm- canClientEncryptPasswords- executeRepositoryTargeter

DPS.WebServices


these Web services, see

the ATG Personalization

Programming Guide

Messaging - sendPageVisit- sendClickThrough

DCS.WebServices


these Web services, see ATG

Commerce Programming

Guide.

Order - createOrderFromXML- submitOrderWithReprice- cancelOrder- getOrderStatus- getOrderAsXML- getOrdersAsXML- getOrderStatus- getCurrentOrderId- addItemToOrder- addItemToShippingGroup- createOrder- createOrderForUser- removeItemFromOrder- setItemQuantity- addCreditCardToOrder- addShippingAddressOrder- removePaymentGroupFromOrder- removeCreditCardFromOrder- removeShippingGroupFromOrder- moveItemBetweenShippingGroups- removeItemQuantityFromShippingGroup- setOrderAmountToPaymenGroup- getDefaultPaymentGroupId- getDefaultShippingGroupId

Application Module Web Application Web Services

Pricing - calculateOrderPrice- calculateOrderPriceSummary- calculateItemPriceSummary

Promotions - grantPromotion- revokePromotion- claimCoupon- getPromotionsAsXML

Inventory - getInventory- getInventoryStatus- setStockLevel- setStockLevels

Catalog - getProductXMLById- getProductXMLByDescription- getProductXMLByRQL- getProductSkusXML- catalogItemViewed

Profile - setDefaultShippingAddress- setDefaultBillingAddress- setDefaultCreditCard- getDefaultShippingAddress- getDefaultBillingAddress- getDefaultCreditCard

1 Creating Custom Web Services 5

1 Creating Custom Web Services

The ATG platform provides infrastructure and tools that enable you to expose a wide range of ATG functionality

as Web services. There are three kinds of Web services you can create that expose ATG 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 the ATG Web services support:

JAX-RPC

Automatic generation of Web services

Session and security support

Limitations

6 1 Creating Custom Web Services

JAX-RPC

The Web services support in the ATG platform is based on JAX-RPC (Java API for XML-based RPC). The JAX-

RPC specification defines a standard way for incoming XML-based SOAP messages to be converted to Java-

based RPC calls. The ATG platform uses Suns 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 ATG 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 41) chapter. For more information about using sessions with .NET clients, see the Accessing ATG

Web Services from .NET Clients (page 53) chapter.

Limitations

You can create Web services from most Nucleus methods, both from components ATG 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 thatyou 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 ATG) 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 thewizard 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 ofgenerating 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 theexisting 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 ATG 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 ATG platform implement the interface javax.xml.rpc.server.ServiceLifecyle,and extend the atg.webservice.ManagedComponentProperties class, which registers services with theATG 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 Nucleusmethod being exposed. For instance, if the Nucleus method is getOrderStatus, the service endpoint interfaceis 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 platform-

independent 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 ATG 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:

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:

The location specified is relative to the primary WSDL document. Some Web service clientsare able to interpret relative locations, but others require fully qualified URLs. To work with these

clients, when the ATG platform receives a request for a WSDL document, it uses the servlet class

atg.webservice.WSDLFinderServlet and the filter class atg.webservice.WSDLImportFilter totranslate the location value into a fully qualified URL:


1. At runtime, JAXRPCServlet updates the SOAP address in the WSDL document to include the domain hostname and port number.

2. When WSDLFinderServlet detects a WSDL request, WSDLImportFilter appends the domain nameand port number (from the SOAP address provided by JAXRPCServlet) and the context path (by callingrequest.getContextPath() on the Dynamo request) to the location value in the import statement. Theresulting import statement looks similar to this:

The WSDLFinderServlet and WSDLImportFilter classes are declared in the web.xml file for the Webapplication that the Web service is a part of, as discussed in the next section. For more information about

request handling, see the ATG 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 ATG 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 referenceimplementation, 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 filelooks something like this:

getOrderStatus getOrderStatus com.sun.xml.rpc.server.http.JAXRPCServlet configuration.file WEB-INF/wsconfig/getOrderStatus_Config.properties

...

getOrderStatus /getOrderStatus/*

When a call to the getOrderStatus Web service is sent to the ATG platform, the JAXRPCServlet receives therequest and dispatches it based on the information in the file that the configuration.file parameter pointsto. This configuration file is included in the WAR file, and looks similar to this:

port0.wsdl.serviceName=GetOrderStatusSEIServiceport0.tie=webservices.GetOrderStatusSEI_Tiewsdl.transform=trueport0.name=getOrderStatusportcount=1wsdl.location=WEB-INF/getOrderStatus.wsdlport0.servant=webservices.GetOrderStatusSEIImplport0.wsdl.targetNamespace=http\://www.atg.com/webservices


port0.wsdl.portName=GetOrderStatusSEIPort

Note that the port0.servant property is set to the name of the service implementation class. This propertydesignates 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 parentdirectory that has subdirectories holding WSDL documents.

WSDLFinder, which is a servlet of class atg.webservice.WSDLFinderServlet, should be defined andmapped to each path that will lead to a WSDL document.

For example:

WSDLImportFilter atg.webservice.WSDLImportFilter

...

WSDLImportFilter /getOrderStatus/*

...

WSDLFinder WSDLFinder Used to lookup imported wsdl files. atg.webservice.WSDLFinderServlet

...

WSDLFinder atg.commerce.order.status.wsdl

WSDLFinder atg.security.wsdl

WSDLFinder atg.commerce.wsdl

Web Service Registrar

To register Web services with the Web Services Registry, the web.xml file declares the WebServiceRegistrarservlet, and sets it to load on startup:

WebServiceRegistrar WebServiceRegistrar ATG WebServiceRegistrar for registering servlet


web-services. atg.webservice.WebServiceRegistrar 1

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 Webapplication

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 Webservices 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 ofthe 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 namedgetOrderStatusMapping.xml.

Runtime Classes

The runtime classes are generated using the Sun JAX-RPC reference implementation. These classes include:

the tie class that JAXRPCServlet invokes the method on, and which in turn invokes the method on theservice 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, andJAX-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

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 ATG security

API, see the Managing Access Control chapter in the ATG Programming Guide.

Security Components

There are two primary components involved in securing a Web service method:

/atg/webservice/security/NucleusSecurityManager (an instance ofatg.webservice.NucleusSecurityManager) uses the security configuration associated with the Webservice to apply the corresponding security policy and ACL, to determine whether to grant or deny access.

/atg/webservice/security/NucleusSecurityRepository (an instance ofatg.adapter.gsa.GSARepository) stores the Web service security configurations used by theNucleusSecurityManager.

NucleusSecurityManager

At startup time, the NucleusSecurityManager retrieves the repository items from theNucleusSecurityRepository (described below) and creates an internal mapping between each functionalname 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 securityconfiguration, 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 associatedSecurityPolicy component and ACL, applies them to the call, and returns the result (true or false) to theclient. 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 (forexample, if the SecurityPolicy is not valid), it determines whether to grant access based on the value ofits defaultGrantAccess property. The default value of this property is true (grant access). This settingfacilitates 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 ATG platform, the defaultGrantAccess property is setto false. Note, however, that this means that each of your Web services must have an associated securityconfiguration, 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 includesa single item descriptor called nucleusSecurity, which has properties called functionalName, policy, andACL. The NucleusSecurityManager parses the items in this repository at startup time.


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 /home directory. The Webservice 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 aNucleus-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 ATG 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 assembleyour application.


For more information about the runAssembler command, see the ATG Programming Guide. For informationabout 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 informationabout 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:


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 fileis the value of the wsdl.location property in the configuration file for the JAXRPCServlet. The Securityfunctional name is the name that the service implementation class passes to the hasAccess() method of theNucleusSecurityManager 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 registeringthe service. In addition, the web.xml file for the Web application the service is part of declares theWebServiceRegistrar servlet, as described in the Web Service Registrar (page 12) section.

2 Creating JMS Web Services 19

2 Creating JMS Web Services

In addition to Web services that call Nucleus methods, the ATG platform enables you to create Web services that

send JMS messages through Patch Bay. Many events in the ATG 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 ATG 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 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 isa String, stored in the messages header, that identifies the kind of message it is. For example, a message of

JMSTypeatg.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 thestandard 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 serviceimplementation interface is named SendPageVisitSEI, and the service implementation class is namedSendPageVisitSEIImpl.

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/

20 2 Creating JMS Web Services

dynamo/messaging/MessageImporter. This method receives the message object and forwards it into PatchBay.

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 arehard-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 theclients 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 41) 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 53) chapter.

Patch Bay Configuration

The /atg/dynamo/messaging/MessageImporter component, whose receiveObjectMessage() methodis 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 themessage type.

The standard Patch Bay configuration file, /atg/dynamo/messaging/dynamoMessagingSystem.xml,includes the necessary declarations for the message source and destinations:

/atg/dynamo/messaging/MessageImporter

IndividualEvents

2 Creating JMS Web Services 21

patchbay:/sqldms/MessageImporter/IndividualEvents Topic GlobalEvents patchbay:/sqldms/MessageImporter/CollectiveEvents Queue

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 isconfigured 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 thisdestination 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 globalscenario events to, and configure your sink to listen to that destination instead.

22 2 Creating JMS Web Services

3 Creating Repository Web Services 23

3 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 clickingthe 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:

addremove

updateget

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.

24 3 Creating Repository Web Services

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 /home directory, with thename 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-p

Date post:	11-Oct-2015
Category:	Documents
Upload:	satish-pandey
View:	71 times
Download:	0 times