Chapter 15. Administering Web Services
The AdminApp, AdminConfig, and AdminTask scripting objects are all useful in configuring Web services in WebSphere. In this chapter, we consider the following topics:
What are Web services?
• The Java standards, JAX-RPC (JSR-101) and JAX-WS (JSR-224), used to author Java-based Web services.
• The Web service for Java EE (JSR-109) specification, which dictates how Java-based Web services run in environments such as WebSphere.
The WSEE (JSR-109) Deployment models supported by WebSphere:
• SOAP/HTTP using a “Plain Old Java Object” (POJO)
• SOAP/HTTP using a Stateless Session EJB
• SOAP/JMS using a Stateless Session EJB
WebSphere scripting support for Web services:
• The introduction of Web service policies, which can simplify almost inherently complex administrative tasks related to Web services.
The WS-Security specification, which covers such things as authentication, non-repudiation, confidentiality, and integrity for Web services and presents examples of scripted administration of these issues.
Web Services Basics
Web services are at the core of the Service-Oriented Architecture approach to application development that is increasingly being deployed within and between enterprises. But while a Web service application is installed just like any other application, after it is deployed, there are several possible administrative activities. To understand those activities, it helps to know a bit about what Web services are and how they work.
The idea of a Web service is fairly simple; the majority of Web services look like Remote Procedure Calls. To use Web services terminology, they use one of two “Message Exchange Patterns”: Request-Response and One-Way.
Because Web services are essentially providing Remote Procedure Call behavior, you might ask what makes them special and worth the hype. In one word, the answer is interoperability.
To ensure interoperability—the raison d’être of Web services—they should adhere to the Web Services Interoperability Organization (WS-I—http://www.ws-i.org) profiles. These profiles ensure that regardless of whether a Web service is written using the following:
• C#® on Microsoft® .NET platform
• C# on Novell’s Mono platform
• Java on WebSphere
• Java on WebLogic
• Python using any of a number of libraries, such as
• SUDS—Arguably the best for WSDL-based clients
• soaplib—Possibly the easiest for SOAP-based Web services
or any other combination programming language, runtime environment, operating system, hardware platform, and so on, the Web services can all communicate and interact with each other. In other words: interoperate. This can be even more challenging than might appear at first because even seemingly simple things like dates and times can be problematic. Fortunately, these issues are in the hands of developers, so you can focus on the problems that present themselves to administrators.
WS-I Profiles
A WS-I profile is basically a standard that lists other existing standards and explains how to use them in combination to achieve interoperability—across all languages, operating systems, and hardware platforms. There are many (some would argue far too many) additional specifications. Only a very few, such as WS-Security, are true standards. And even amongst those, interpretation varies because in the real world specifications are not unambiguous.
The WS-I profiles dictate which of the myriad WS-* specifications are actually to be considered interoperable standards—therefore permissible to use—and how to use them in the appropriate manner. The WS-I also provides conformance testing tools to help ensure that interoperability is achieved.
The key profiles from the WS-I are as follows:
Basic Profile
• Fundamental profile that permits us to build interoperable Web services.
• Covers SOAP, WSDL, and (in recent revisions) WS-Addressing and MTOM (attachments).
• Bans the use of Section 5 (SOAP Encoding) of the SOAP specification in its entirety.
• Mandates the use of HTTP as the transport and details how to do so.
Basic Security Profile
• Adds support for WS-Security with a specific set of security tokens, such as user name and password and X.509 certificates. You would add this profile when implementing:
• Authentication
• Integrity
• Confidentiality
Reliable Secure Profile (RSP)
• Adds support for WS-ReliableMessaging and WS-SecureConversation. You would generally use either the Basic Profile or the Basic Security Profile with most Web services, although the use of the RSP profile is gaining adoption, now that more Web services runtime environments offer support for it. This is one of the challenges: Even with WS-I profiles, there’s no guarantee which profiles your partners will use. Someone will need to tell you which ones—which policy—to administratively apply to any given Web service, based on business requirements.
WSDL and SOAP
The WS-I mandates that Web services are described using the Web Services Definition Language (WSDL) and that they exchange SOAP messages. It is helpful to know something about these fundamental specifications.
A WSDL document is an XML document that describes the interface to a Web service. The essential structure of a WSDL document is as follows:
• Data Types—This section uses XML Schema to define the types of data that is exchanged between the Web service requester and Web service provider.
• Messages—Web services work by exchanging messages. This section describes the messages that will be exchanged. The messages contain the data types previously defined.
• Service Interface—This is known as a Port Type in the currently mandated version of WSDL and describes the interface to the Web service.
• Operations—The service interface consists of defined operations. Each operation is defined in terms of messages:
• Input[required]—This is the message sent to the Web service to initiate the request.
• Output[optional]—This is the message sent by a Web service if it follows a request-response (RPC) pattern.
• Fault[optional]—This is the message sent by a Web service to indicate some sort of exception, a.k.a., fault.
• Binding—This section describes how to map the generic definition of the Web service (bullets 1–3 in this list) to a specific transport, such as HTTP and formatting.
• Service—This section describes the location (endpoint) of the Web service, such as an HTTP URL or JMS queue.
The WSDL could be generated for developers if they had started by writing a Web service using some tooling environment, or they could have received the WSDL from some standards body or from you if they are writing code to match an existing Web service already deployed in the environment. In the later case, developers can start from a WSDL document and generate the necessary code to begin implementing a Web service client or a similar Web service provider.
A SOAP document is also an XML document and is the data format used for all messages between Web service requesters and providers. The essential format of a SOAP document is as follows:
• Envelope[required]—This wraps the entire SOAP message.
• Headers[optional]—This can contain all sorts of metadata about the message and is used extensively when using specifications such as WS-Security.
• Body[required]—This contains the payload—the message—being exchanged.
A Web Service Example
To put some of what we’ve covered so far in perspective, let’s take a quick look at a very simple Web service. Don’t worry if you are not a Java programmer; the operative word here is “simple.”
The Web service provider is implemented as a single Java class, PingService, with a single operation (ping) that takes a string as a parameter and returns the same string. The class implementation is represented in Listing 15.1.
Listing 15.1 ping Service Java Code
Developers can implement the class in Rational® Application Developer or other similar tooling, along with client code, and deliver the resulting EAR file(s) to the administrator for deployment and administration.
A Java client might be as simple as the code in Listing 15.2.
Listing 15.2 ping Client Java Code
The sole purpose for showing you these trivial examples is to emphasize the point that there is nothing magical happening in the programs themselves. Other than an annotation, @WebService, in the service and the use of PingServiceProxy in the client, there was nothing “Web service-ish” in either of them. The essential magic to make them Web service providers and Web service requesters, respectively, happens within vendor-provided code generators or within WebSphere Application Server1 itself. And that’s the catch and the reason for the code just shown. Administrators configure the magic (a.k.a., the Web services runtime environment) to make interesting things, such as WS-Security or other non-default behaviors, happen. A sample partial WSDL2 for this Web service is shown in Listing 15.3.
1 WebSphere Application Server provides the underlying Web service runtime environment.
2 Web Services Descriptor Language. This document tells clients of the service how to request your service and what, if anything, will return to them when they make a request. For extensive details, see http://www.w3.org/TR/wsdl20/.
Listing 15.3 Partial WSDL Document for the ping Web Service
A pre-existing XML type was used here, so there is no section for defining types, and the binding and service sections are not shown. The resulting messages would be similar to what is presented in Listing 15.4.
Listing 15.4 SOAP Messages Exchanged Between Client and ping Service
Again, this is nothing fancy. But, it gets a lot more complicated when you want to take advantage of additional capabilities, such as digitally signing the messages and encrypting the messages. When that happens, the code stays the same, and the WSDL stays the same. However, the way you configure the Web services runtime environment will have to change. The information in the message headers will explode in size and complexity. In this example, those headers are empty now. As you add features to the Web service, the runtime environment must add quite a bit of information to the header section of each message. The Web services runtime environment decides what to put in various headers based on configuration data that the administrator’s supply. Much of Web services’ flexibility comes directly from configuration decisions that the administrators make.
Web Services Runtimes
WebSphere ships with and supports more than one Web services runtime environment. The two that are of importance to us are as follows:
• JAX-RPC (JSR-101)—This is the first specification for writing Web services in Java.
• JAX-WS (JSR-224)—This was initially called JAX-RPC v2 and is the second and current specification for writing Web services in Java. It is supported only by WebSphere V7 (or WebSphere V6.1 with the Web services Feature Pack).
It is important for you to know that these specifications exist and are supported. For one thing, many of the new administrative capabilities for managing Web services in WebSphere V7, including the related AdminTask command groups, work only with Web services implemented using JAX-WS and not those written using JAX-RPC.
Another vital specification is Web Services for Java EE (JSR-109) a.k.a., WSEE, which specifies how to deploy Web services written using either JAX-RPC or JAX-WS in a Java EE application server (which is what WebSphere provides).
WSEE defines a few different approaches to deploying Web services. In summary, these are:
• A “Plain Old Java Object” (POJO) using SOAP over HTTP. This is the kind of Web service implemented earlier. It is deployed as part of a web module into the web container. The web container is responsible for implementing all of the technology necessary for the Web service to work properly. Authorization is at the level of the Web service interface, not individual operations.
• An EJB using SOAP over HTTP. Developers write a normal Stateless Session Bean—a type of Enterprise Java Bean (EJB). That EJB is deployed as part of an EJB module into the EJB container. Because the EJB container does not handle HTTP traffic—that’s the job of the web container—it is typical to see a companion web module automatically generated to match the Web service and deployed in the EAR file along with it. The web module deploys to the web container and routes the Web service request to the EJB in the EJB container. There are several advantages to this type of Web service implementation:
• The Web service runs in a transactional environment (the EJB container).
• Individual Web service methods can be restricted so that only authorized users can invoke them.
• An EJB using SOAP over JMS. Developers write a normal Stateless Session Bean—a type of Enterprise Java Bean (EJB). That EJB is deployed as part of an EJB module into the EJB container. Because the EJB exposes the Web service interface and does not natively communicate with JMS, the Web service runtime is responsible for making the connection. IBM’s JAX-RPC runtime, for example, provides a Message-Driven Bean (MDB) to help bridge the gap between JMS and the Web service.
• As an administrator, there is more work to do here because you need to create the JMS resources, that is, JMS queues for exchanging messages and an Activation Specification to link our request queue to the MDB.
• This model includes the advantages of the EJB using SOAP over HTTP approach and others, such as: The Web service requester and provider are decoupled in time. At the time that the request is made, the requester only needs to be able to post to a queue. Messages from the queue can be delivered when the Web service provider is available.
• Because this deployment model does not use HTTP, it is not WS-I–compliant. The reason for this is that there is not an accepted standard for SOAP over JMS across all of the Java EE vendors. But work is progressing rapidly on such a standard, and WebSphere V7 has support for the current draft.
Irrespective of the ability to interoperate with other JMS providers, JMS is still not interoperable with non-Java platforms. Again, the mandate for HTTP is to ensure interoperability between Web services, regardless of programming language, operating system, or hardware platform.
Managing Web Services
The examples in this chapter use the AdminApp, AdminConfig, and AdminTask administrative objects, as appropriate, to manage Web services. As noted earlier, many of the AdminTask commands discussed do not exist in WebSphere V6.1. You must be using WebSphere V7 (or WebSphere V6.1 with the Web services Feature Pack). For purposes of this chapter, it is assumed that you are using WebSphere V7.
It is also assumed that by now you are familiar with AdminConfig.save() and AdminConfig.reset() and know when to use each,3 so they have been left out of the given examples. The complete code examples can be found on the book’s FTP site. The following sections cover key segments.
3 See the “Create and Modify Methods” section in Chapter 8, “The AdminConfig Object,” for details.
Exploring Web Services
First, let’s look at how to explore the Web services that might already be installed in your WebSphere environment. The interactive mode of wsadmin will be used for this exploration.
For purposes of illustrating the scripts, we have already created and deployed our Web service (described previously) in the following applications:
• [JAX-WS] PingServiceApplication
• [JAX-WS] PingServiceClientApplication
• [JAX-RPC] PingServiceJAXRPCApplication
• [JAX-RPC] PingServiceJAXRPCClientApplication
The code for the Web service requester and Web service provider is essentially identical in all cases. They differ only in the use of JAX-RPC or JAX-WS.
Listing Web Services
In preparation, you might want to simply list the applications that are installed, as in Listing 15.5.
Listing 15.5 List Applications
In Listing 15.5, you can see four applications: two Web service requesters and two Web service providers. The method named and the documentation for AdminTask.listWebServices() and related methods might lead you to believe that you can use these methods to investigate the Web services, but look closely at the results in Listing 15.6.
Listing 15.6 List (JAX-WS) Web Services
As seen in Listing 15.6, there is a surprise: Where is the service for PingServiceJAXRPCApplication? It is not there because not only are these AdminTask commands new for WebSphere V7, but they only work for new, JAX-WS-based, Web services.
Note, too, that in Listing 15.6, AdminTask.listWebServices()4 only listed the service provider. If you want to see the client(s), you have to add a parameter as shown in Listing 15.7:
4 See details in the reference section of this chapter.
Listing 15.7 List (JAX-WS) Web Services Clients
In Listing 15.7, the command has only provided information about JAX-WS clients. If you are using JAX-RPC-based Web services, these commands provide no information. The AdminTask methods only provide information for JAX-WS web services and their clients.
Listing Web Services Information
Two other useful commands are AdminTask.listWebServicesEndpoints5 and AdminTask.listWebServicesOperations.6 From AdminTask.listWebServicesEndpoints, you can get the endpoints as defined in WebSphere, as shown in Listing 15.8.
5 See details in the reference section of this chapter.
6 See details in the reference section of this chapter.
Listing 15.8 Listing (JAX-WS) Web Service Endpoints
This might not seem useful, but that logicalEndpoint attribute is necessary for the AdminTask.listWebServicesOperations command, as shown in Listing 15.9.
Listing 15.9 Listing (JAX-WS) Web Service Operations
This section has listed the available Web service operation(s), but not sufficiently enough for the developers to understand nor in sufficient detail to understand the SOAP messages that might be exchanged. For that, you need the WSDL for the Web services.
Exporting the WSDL for a Web Service
There is an AdminApp command to export the WSDL for a Web service, which also works for JAX-RPC-based Web services.
wsadmin>AdminApp.publishWSDL("PingServiceJAXRPCApplication",
"/tmp/PingWSDL.zip")
The WSDL related for the Web service will be written to the specified location. The .zip is not really optional. You can specify whichever filename you want, but the result will still be a ZIP-formatted archive, no matter what you call it. One reason is that WSDL documents support an import operation. The document can be broken into multiple parts that are reusable components. For example, the data types might be used in many different Web services using different messages. So WebSphere writes a ZIP-formatted archive to hold the possibly multiple parts that makeup the logical document.
Web Service Policy Sets
WebSphere V7 introduces the administrative notion of policy sets. Policy sets allow you to declare Qualities of Service (QOS) for Web services, store them separately, and apply them to various Web services. The overall structure surrounding policy sets is fairly simple:
• Policy Set—A collection of policies. WebSphere V7 comes with a number of preconfigured policy sets.
• Policy7—A collection of QoS attributes defined in general terms.
7 See details at http://www.w3.org/Submission/WS-Policy/.
• Policy Set Bindings—Mapping between general terms, used in policies and actual values. These allow policies to be defined fairly generically and then reused with specific values for such types of information as the following:
• Keys and keystores, which are used for signature and encryption
• Authentication information
• Persistent information
• Policy Set Attachment—Associates a Web service with a policy set. Attachments can be made at any of the following four levels:
• Application
• Web service
• Endpoint
• Operation
WebSphere V7 comes with sample policy set bindings, which you can use as examples for the ones created here. You can list the available policy sets with AdminTask.listPolicySets()8 as in Listing 15.10.
8 See details in the reference section of this chapter.
Listing 15.10 Application Level Policy Sets
Those are not all of the available policy sets. AdminTask.listPolicySets() takes a parameter, policySetType, which can have one of several values: application, system, system/trust, default, and application. The default is application (yes, despite the seeming oddity, default is not the default). Regardless, the default does not show all available policies, so you have to loop through them, as shown in Listing 15.11.
You can now use AdminTask.getPolicySet()9 to get more information on any of these policy sets. You will find it is easier to use a Python list as the parameter rather than a string due to the presence of spaces in the policy set names. Without proper formatting, you would receive a CWPST0055E: The {} policy set is not found exception. You could use nested quotes to work around that issue, but a Python list is used here, instead, which also makes it easier to vary the parameter list.
9 See details in the reference section of this chapter.
Please note the technique used to build these parameter lists. With it a list is prepared in which some number of list members are of the form "%(variableName)s", and then a list comprehension is used along with the python construct string % locals() to create a new list in which all of the "%(variableName)s" entries have been replaced with the current value of those variables in the local scope. This can be a very nice technique for preparing and reusing parameter lists when working with scripting objects. Listing 15.12 shows one policy set.
Listing 15.12 The SecureConversation Policy Set
Listing 15.13 shows that you can obtain details about a different policy set simply by changing the name that is passed to AdminTask.getPolicySet().
Listing 15.13 The WSSecurity Policy Set
These two seem pretty similar when you look at the descriptions, except for the comment about WS-SecureConversation. So what is the difference? There are different ways to explore that topic, but a quick way to do so is to export the two policy sets,10 as shown in Listing 15.14, and then view the results in an editor.
10 See the details of AdminTask.exportPolicySet() in the reference section of this chapter.
Listing 15.14 Exporting Policy Sets
As it turns out, there are two policies in each of these policy sets: WS-Security and WS-Addressing. By looking at the XML files for their WS-Addressing policies, you can immediately see that they are identical, so these two policy sets differ only in their WS-Security policy configuration.
Alternatively, in Listing 15.15, you can see which policies are contained in a policy set by using the AdminTask.listPolicyTypes()11 command.
11 See the details of AdminTask.listPolicyTypes() in the reference section of this chapter.
And Listing 15.16 lists the attributes of the policy via the AdminTask.getPolicyType()12 command.
12 See details in the reference section of this chapter.
Listing 15.16 Policy Attributes
But, there is a reason why you won’t see the voluminous output in this book. It is far easier to view the XML representation of the policy than to view the response from that command. In fact, although there are commands for setting the policy attributes, if you need to modify a policy, you might well want to export13 the policy set, edit the WS-Policy files (those XML files in the archive), and import14 the modified policy set.
13 See details of AdminTask.exportPolicySet() in the reference section of this chapter.
14 See details of AdminTask.importPolicySet() in the reference section of this chapter.
Another important reason for exporting policy sets is that the Rational Application Developer (RAD) tool used by your programmers can use but cannot create policy sets (as of RAD 7.5.2), so the pattern of use is to export policy sets from WebSphere and import them into RAD.
As you’ve seen, a policy set describes a set of policies for how to apply various Web service capabilities, such as WS-Security and WS-Addressing, to Web services. They are sharable and reusable. In fact, given that you want Web services to be able to interoperate, the requester and the provider need compatible policies. When they are installed in WebSphere, you would use the same policy set with each.
Rather than use the default policy sets that come with WebSphere, we recommend you make a copy. That way, you can avoid accidentally impacting other Web services when you modify a policy set. A couple of AdminTask commands can help here: AdminTask.listAttachmentsForPolicySet()15 and AdminTask.copyPolicySet().16 Both are shown in Listing 15.17.
15 See details in the reference section of this chapter.
16 See details in the reference section of this chapter.
Listing 15.17 List Attachments and Copy Policies
The attachments (uses) of the policy set have been listed and copied, as well as a copy made without copying any attachments so that there would be no worry about future change(s) unintentionally impacting unrelated Web services.
Policy Set Bindings
The policy set that created here can be attached to the Web service requester(s) and provider(s), but the policies are general and need to be bound to specific resources, such as the specific keys and keystores to use for cryptography with the WS-Security policy. Typically, bindings are specific to the application and/or platform. In this example, the bindings are specific to the platform—keys and keystores—but not to the application. Don’t be confused by the names chosen for the keys and keystore files—such things could be specific to an application, but in this case they are not.
To perform a binding, you need something to bind to, and for WS-Security, you need such things as keys and keystores. Before creating the bindings, you need to prepare some resources. For the purposes of this example and for reference, these were the commands used:
Create Server Key Pair
Create Client’s Key Pair
Export Server’s Public Key
Export Client’s Public Key
Import Client’s Key Into the Server’s Keystore
Import Server’s Key Into the Client’s Keystore
As indicated, these commands have created the necessary messaging resources used with WS-Security using the standalone keytool provided with WebSphere’s implementation of Java.17 Because this is using platform-specific bindings, rather than application-specific, let’s start by copying one of the default bindings provided with WebSphere.You can query the default bindings with AdminTask.getDefaultBindings().18
17 It is located in ${INSTALL_ROOT}/java/bin/keytool[.exe].
18 See details in the reference section of this chapter.
And you can easily copy the binding. In this case, you see the provider binding completed in Listing 15.18, but we’re leaving the consumer binding as an exercise for you.
Listing 15.18 Copy Provider Bindings
Now you need to bind the physical keys and keystores to logical references that are used by the WS-Security policy in our policy set. And this is where things get rather tricky. This is where things get...ugly, to be honest. The WebSphere Application Server V7 Information Center topic, Enabling secure conversation using wsadmin scripting, provides an example of what you need to do. For all intents and purposes, it is presented without any explanation at all. You need to set properties on the bindings, and there is basically no documentation on what those properties are and how they need to be set. In cases such as this, once again, you can and should turn to the Command Assistance feature of the Integrated Solutions Console to see the commands that it generates. It does not generate optimal commands, but it does provide the necessary properties.
You can also query the current set of properties using AdminTask.getBindings().19 Listing 15.19 shows the code.
19 See details in the reference section of this chapter.
Listing 15.19 Getting Binding Information
We’ll spare you the page or two of output that this emits.
To bind the keys and keystores, the AdminTask.setBinding() command is used to modify the policy set binding’s contents. The AdminTask.setBinding() command is also used to associate the policy set binding with a policy set attachment, as you will see later on, as well as to delete the binding from the system.
To delete a binding, you use the -remove parameter with AdminTask.setBinding().20 See the example in Listing 15.20.
20 See details in the reference section of this chapter.
Now you need to perform the steps to bind the necessary resources for the WSSecurity policy type. For the purposes of this example, these steps are as follows:
• Add the service’s keystore file as a “trust store.” This allows you to trust requesters whose public keys are in your keystore.
• Configure the consumer of incoming signed requests to use the newly added trust store.
• Configure the generator used to generate your signed responses to use your keystore and key.
• Configure the consumer of incoming encrypted requests to use your keystore and key.
• Configure the generator used to generate your encrypted responses to use your keystore and the client’s key.
The AdminTask.setBinding() command is used for all of these steps. The primary parameter of interest is one called attributes. You can see partial code for how this is used to add the keystore as a trust store in Listing 15.21.
Listing 15.21 Partial Code for Configuring a Policy Set Binding
There are many more parameters that need to be set in a working example. Please visit the companion website, http://www.wasscripting.com, for complete examples.
Actually, one interesting thing is that because of the way AdminTask.setBinding() works, you can combine many logical steps into one call, as they are all just properties of the overall policy set binding.
After you have completed a policy set binding, you can export it, as is seen in Listing 15.22. You might wish to import it into Rational Application Developer 7.5 or edit the bindings by hand in a text editor.
Policy Set Attachment
Having created the Policy Set, you now need to attach it to a Web service requester and/or provider to put it into effect. Listing 15.23 illustrates the configuration options on the server side, also called the provider side, of a Web service.
Listing 15.23 Server-Side Policy Attachments
Listing 15.24 shows the configuration for the client side, also known as the requester side, of a Web service.
Listing 15.24 Client-Side Policy Attachments
You would never attach the policy sets for both the Web service requester and the Web service provider to the same server. We’re just trying to illustrate all of the different constructs for the -resources parameter to specify the level to which you want the policy set attached and how those levels relate to one another. You would only build the resource reference out to the desired level.
Notice, too, that other than the name of the WAR file, the resource specification was identical for both the Web service requester and provider.
Important
AdminTask.createPolicySetAttachment()21 returns a value, specifically an attachment id. You will need that when attaching a binding for the policy. You have two choices: You can either assign it to a value now, or attempt to locate it later using AdminTask.getPolicySetAttachments().
21 See details in the reference section of this chapter.
In Listing 15.25, the id returned, AdminTask.createPolicySetAttachment(), is the same as the attachmentId attribute received by calling AdminTask.getPolicySetAttachments().
Listing 15.25 Setting Policy Set Attachments
Given that id, you can now complete the job of associating the Policy Set Attachment and the necessary Policy Set Binding. Use the same mechanism for creating the argument list as before, except that this time instead of setting attributes, set the bindingLocation.
Listing 15.26 associates a policy set binding with an application and policy set attachment.
Listing 15.26 Associate Policy Set Binding with Application and Policy Set Attachment
Policy Topics Summary
This concludes our look the Policy Sets, Policy Set Attachments, and Policy Set bindings used to configure WS-Security for a Web service provider. Hopefully you have a feel for the kinds of Web services-related topics that you can script in WebSphere. We’ve discussed what Web services are, how to list them (only works for new Web services using JAX-WS), how to export the WSDL so that you can give it to developers, and the use of Policies for configuring such things as WS-Security. However, there is much more that you can do with Web services and scripting than we can cover in this chapter.
Additional Topics
This last section offers a brief overview of additional Web services functions not covered in detail within this book.
Enable/Disable Endpoints
You can selectively enable and disable the JAX-WS Web services without having to stop the rest of the application. This is performed using AdminControl and is discussed in the WebSphere V7 Information Center topic, Administration of service and endpoint listeners.
WS-Notification
Web services are often point-to-point, but the WS-Notification specification permits them to participate in a topic-oriented, publish-subscribe, communication model. WebSphere supports WS-Notification, and you could configure those resources using scripting. There are a number of sections in the WebSphere Information Center that provide additional information:
• Learning about WS-Notification
• Using WS-Notification for publish and subscribe messaging for Web services
Web Services and the Service Integration Bus
Instead of having the Web service requester attach directly to the Web service provider, you can configure Web service endpoints on the Service Integration Bus. There are a number of benefits to this approach. A number of sections in the WebSphere Information Center provide additional information:
• Learning about bus-enabled Web services
• Enabling Web services through the service integration bus
Mediations
Once you are using the Service Integration Bus, you can perform mediation on the incoming and outgoing messages using SIB Mediations. Mediation refers to the ability to modify the routing and content of messages. WebSphere comes with a powerful mediation feature built in, although it is not as easy to use and deploy as the even more powerful capabilities provided by WebSphere Enterprise Service Bus. For addition information, see the following:
• The WebSphere V7 Information Center topic: Administering Mediations
• IBM developerWorks: Mediations made simple (http://www.ibm.com/developerworks/webservices/library/ws-mediation/)
Web Services Gateway
The Web services gateway component of WebSphere works with the Service Integration Bus and allows for a single point of control for entire sets of Web services, which may be both internally hosted and externally hosted. The Web services gateway is discussed in the WebSphere V7 Information Center topic, Learning about the Web services gateway.
Online References
The WebSphere Information Center is always a good source of information that you should review. There are specific sections for learning about managing Web services, both in general and specifically via scripting. In addition, we have selected a few of our favorite IBM developer-Works articles that relate to the topics discussed in this chapter.
For additional reading on configuring WS-Security with WebSphere, we recommend the IBM developerWorks tutorial, Message-level security with JAX-WS on WebSphere Application Server v7 (https://www.ibm.com/developerworks/websphere/tutorials/0905_griffith/). It uses the Integrated Solutions Console and Rational Application Developer, whereas we use scripting, but it goes into more detail on the underlying WS-Security concepts.
For additional reading on WS-Notification support, we recommend the IBM developerWorks articles WS-Notification in WebSphere Application Server V7: Part 1: Writing JAX-WS Applications for WS-Notification (http://www.ibm.com/developerworks/websphere/techjournal/0811_partridge/0811_partridge.html) and WS-Notification in WebSphere Application Server V7:Part 2: Configuring JAX-WS Applications with WS-Security for WS-Notification (http://www.ibm.com/developerworks/websphere/techjournal/0904_jiang/0904_jiang.html).
For additional reading on JAX-WS using SOAP/JMS, we recommend the IBM developerWorks article Develop a SOAP/JMS JAX-WS Web services application with WebSphere Application Server V7 and Rational Application Developer V7.5 (http://www.ibm.com/developerworks/websphere/library/tutorials/0903_adams/).
AdminTask Web Services Reference
An application that produces or consumes Web services is installed just like any other application. After it is deployed, there are a lot of possible administrative activities. The groups of AdminTask methods you might need to perform those activities depend on which Web service functionality you use. The list of AdminTask groups that relate to Web services include the following:
• WSGateway group
• WSNotificationCommands group
• WSNotifierCommands group
• SIBWebServices group
• KeyManagerCommands group
• KeyStoreCommands group
• KeySetGroupCommands group
• PolicySetManagement group
• WebServicesAdmin group
In addition, you might well need the AdminApp.publishWSDL() method22 to make a WSDL file available to client applications.
22 See “Exporting the WSDL for a Web Service” section in this chapter for details.
The two sections on Web service notifications are outside the scope of this book, as is the WSGateway group. All of the methods in this section are described as they are implemented in version 7.0 of WebSphere Application Server. Some of the AdminTask groups did not exist in earlier versions of the product. Some of the methods in existing AdminTask groups did not exist in earlier versions of the product.
We present a sampling of the methods in each command group in the order we think you might use them in your scripts. The general pattern for calling AdminTask methods is as follows:
There might or might not be a target. If there is, it might be a configuration ID or a name. There might or might not be arguments as well. Most often, arguments are name/value pairs. There might or might not be steps, and there might be more than one step. Think of steps as arguments that take either a list of name/value pairs as their value or no argument at all. Bundle all the arguments and all the steps into one big list and pass it to the method.
SIBWebServices Group
The methods in this group allow you to create Web services and wrap them around existing executables as long as those executables can integrate with a messaging service. The Web services that this group manipulates are the JAX-WS Web services.
createSIBWSInboundService
Creates an inbound service. This task cannot be performed when wsadmin is started in local mode.
Target (mandatory):
The configuration ID, not the name, of the service integration bus where the inbound service will be created.
Required arguments:
• name—The administrative name of the outbound service.
• wsdlLocation—The Web service WSDL location.
Frequently used optional arguments:
• wsdlServiceNamespace—The Web service namespace.
• wsdlServiceName—The Web service name.
• uddiReference—The UDDI reference.
• destination—The name to use for the associated service destination.
Optional arguments that matter if you enable security:
• userId—The user ID to be used if WSDL is obtained through an authorizing proxy.
• password—The password to be used if WSDL is obtained through an authorizing proxy.
createSIBWSOutboundService
Creates an outbound service. This task cannot be performed when wsadmin is started in local mode.
The configuration ID, not the name, of the service integration bus where the outbound service will be created.
Required arguments:
• name—The administrative name of the outbound service.
• wsdlLocation—The Web service WSDL location.
Frequently used optional arguments:
• wsdlServiceNamespace—The Web service namespace.
• wsdlServiceName—The Web service name.
• uddiReference—The UDDI reference.
• destination—The name to use for the associated service destination.
Optional arguments that matter if you enable security:
• userId—The user ID to be used if WSDL is obtained through an authorizing proxy.
• password—The password to be used if WSDL is obtained through an authorizing proxy.
createSIBWSEndpointListener
Create an endpoint listener on a service integration bus. An endpoint listener is the glue that ties a Web service to a messaging bus.
Target (mandatory):
The configuration ID of the server where the endpoint listener will be created.
Required arguments:
• name—Name of the endpoint listener.
• urlRoot—Root of the endpoint address URL for Web services accessed using this endpoint listener.
• wsdlUrlRoot—Root of the HTTP URL where WSDL associated with this endpoint listener is located.
Occasionally used optional argument:
• earFile—Location of the endpoint listener application EAR file.
connectSIBWSEndpointListener
Connect an endpoint listener to a service integration bus. An endpoint listener is the glue that ties a Web service to a messaging bus. This task cannot be performed when wsadmin is started in local mode.
The endpoint listener to be connected.
Required argument:
• bus—The name of the service integration bus to which the endpoint listener will be connected.
Occasionally used optional argument:
• replyDestination—Name to use for the connection’s reply destination.
addSIBWSInboundPort
Add an inbound port to an inbound Web service. This task cannot be performed when wsadmin is started in local mode.
Target (mandatory):
The configuration ID of the inbound service to which the port will be added.
Required arguments:
• name—The name for the inbound port.
• endpointListener—The name of the associated endpoint listener.
Frequently used optional arguments: At least one, and possibly two, of these arguments is actually required. If the endpoint listener lives in a cluster, you must supply the name of the cluster. If the endpoint listener lives on an individual server, you must supply the server name and the node name.
• cluster—The name of the cluster where the associated endpoint listener lives.
• node—The name of the node that contains the server that contains the endpoint listener with which this port will be associated
• server—The name of the server where the associated endpoint listener lives.
• templatePort—The name of the port in the template WSDL to use as a basis for this port’s binding.
addSIBWSOutboundPort
Add an outbound port to an inbound Web service. This task cannot be performed when wsadmin is started in local mode.
Target (mandatory):
The configuration ID of the outbound service to which the port will be added.
• name—The name for the outbound port.
• endpointListener—The name of the associated endpoint listener.
Frequently used optional arguments:
At least one, and possibly two, of these arguments is actually required. If the endpoint listener lives in a cluster, you must supply the name of the cluster. If the endpoint listener lives on an individual server, you must supply the server name and the node name.
• cluster—The name of the cluster where the associated endpoint listener lives.
• node—The name of the node that contains the server that contains the endpoint listener with which this port will be associated
• server—The name of the server where the associated endpoint listener lives.
• templatePort—The name of the port in the template WSDL to use as a basis for this port’s binding.
publishSIBWSInboundService
Publish an inbound service to a UDDI registry. This task cannot be performed when wsadmin is started in local mode.
Target (mandatory):
The configuration ID of the inbound service to be published.
Required argument:
• uddiPublication—The name of a UDDI publication for the inbound service.
Optional arguments that matter if you enable security:
• userId—User ID to be used if publishing is done through an authenticating proxy.
• password—Password to be used if publishing is done through an authenticating proxy.
KeyManagerCommands
A key manager determines which alias to use during the Secure Sockets Layer (SSL) handshake. There is a default key manager. You can also create a custom key manager.
listKeyManagers
Reports the key managers installed in the product. The arguments serve to limit the scope of the report.
Frequently used optional arguments:
• scopeName—Specifies the management scope.
• all—Specifies true to list all key managers. True overrides the scopeName parameter.
• displayObjectName—Specifies true to display the list output as ObjectNames and false to return SSL configuration alias names. If you do not pass this argument, you get SSL configuration alias names.
createKeyManager
Creates a key manager.
Required argument:
• name—Specifies a name to uniquely identify a key manager.
Frequently used optional arguments:
• algorithm—Specifies the algorithm name of the TrustManager or KeyManager.
• scopeName—Specifies the management scope.
• provider—Specifies the provider.
Occasionally used optional argument:
• keyManagerClass—Specifies the custom class that implements the KeyManager interface. You may not specify this argument if you specify either the provider or the algorithm argument.
KeyStoreCommands
Keys are managed in keystores so the keystore type can be supported by WebSphere Application Server, provided that the keystores can store the referenced key type. You can configure keys and scope keystores so that they are visible only to particular processes, nodes, clusters, and so on.
listKeyStoreTypes
List the supported keystore types. This method takes no arguments.
listKeyStores
List keystore objects. For the most part, the arguments serve to limit the scope of the query.
Frequently used optional arguments:
• all—Specifies true to list all keystores. True overrides the scopeName parameter. If you do not specify this argument, the default value is false.
• scopeName—Limits the query to the specified management scope. This argument only matters if you omit all or set all false.
• keyStoreUsage—Limits the query to keystores for a particular usage. If you omit this argument, you get all keystore usages subject to any scope limitation you might have specified.
createKeyStore
Creates a new keystore.
Required arguments:
• keyStoreName—Specifies the unique name to identify the keystore.
• keyStoreLocation—Specifies the name of the keystore file. This may either be a fully qualified file name or a relative file name. We recommend passing a fully qualified file name.
• keyStoreType—Specifies one of the predefined keystore types. The value you pass must be one of the values returned by AdminTask.listKeyStoreTypes().
Frequently used optional arguments:
• scopeName—Specifies the management scope.
• keyStorePassword—Specifies the password to open the keystore. This argument is specified as optional, but if you try to create a keystore without a password, recent versions of WebSphere Application Server throw an exception.
• keyStoreDescription—Statement that describes the keystore.
• keyStoreProvider—Specifies the provider for the keystore.
• keyStoreIsFileBased—Keystore is file-based.
• keyStoreUsage—What the keystore can be used for. Permitted values are SSLKeys, KeySetKeys, RootKeys, DeletedKeys, DefaultSigners, or RSATokenKeys.
• enableCryptoOperations—Specifies true to enable cryptographic operations on hardware devices.
Occasionally used optional arguments:
• controlRegionUser—Specifies this field if creating a writable keystore object for the control region’s keyring. This argument only matters in z/OS environments.
• servantRegionUser—Specifies this field if creating a writable keystore object for the servant region’s keyring. This argument only matters in z/OS environments.
• keyStoreHostList—Specifies a comma-separated the list of hosts where the keystore is remotely managed.
• keyStorePasswordVerify—Specifies the confirmation of the password to open the keystore. Most scripts will not pass this value. If your script processes manually generated responses, this argument exists to save your script the trouble of comparing two password entries for equivalence.
• keyStoreReadOnly—Specifies whether the keystore can be written to or not.
• keyStoreInitAtStartup—Specifies whether the keystore needs to be initialized at server startup or not.
• keyStoreStashFile—Specifies whether to stash the keystore password to a file or not. This only applies to the CMS keystore type.
exchangeSigners
Exchange Signer Certificates between two keystores.
Required arguments:
• keyStoreName1—Keystore name that will exchange signers with another keystore.
• keyStoreName2—Keystore name that will exchange signers with another keystore.
• keyStoreScope1—Specifies the management scope.
• keyStoreScope2—Specifies the management scope.
Frequently used optional arguments:
• certificateAliasList1—Specifies colon-separated list of certificates whose signer will be added to another keystore.
• certificateAliasList2—Specifies colon-separated list of certificates whose signer will be added to another keystore.
getKeyStoreInfo
Returns information about a particular keystore.
Required argument:
• keyStoreName—Specifies the unique name to identify the keystore.
Frequently used optional argument:
• scopeName—Specifies the management scope.
listKeyFileAliases
List personal certificate aliases in a keystore file.
Required arguments:
• keyFilePath—Specifies the fully qualified name of the keystore file.
• keyFilePassword—Specifies the password to the keystore file.
• keyFileType—Specifies the type of the keystore file.
KeySetCommands
The key management infrastructure is based on two basic configuration object types: key sets and key set groups. WebSphere Application Server uses a key set to manage instances of keys of the same type. You can configure a key set to generate a single key or a key pair, depending on the key or key pair generator class. A key set group manages one or more key sets and enables you to configure and generate different key types at the same time. For example, if your application needs both a secret key and key pair for cryptographic operations, you can configure two key sets, one for the key pair and one for the secret key that the key set group manages. The key set group controls the auto-generation characteristics of the keys, including the schedule. The framework can automatically generate keys on a scheduled basis, such as on a particular day of the week and time of day, so that key generation is done during off-peak hours.
createKeySet
Creates a key set.
Required arguments:
• name—Specifies the name that uniquely identifies a key set.
• password—Specifies the password for the key.
• keyStoreName—Specifies the unique name to identify the keystore.
• aliasPrefix—Specifies the key alias prefix name.
• maxKeyReferences—Specifies the maximum number of keys stored.
Frequently used optional arguments:
• isKeyPair—Specifies true if the key set is a key pair, false otherwise.
• deleteOldKeys—Specifies true to delete old keys during key generation, false to retain old keys.
• scopeName—Specifies the management scope.
• keyStoreScopeName—Specifies the management scope of the keystore.
• keyGenerationClass—Specifies the class used to generate keys.
generateKeyForKeySet
Generate all the keys in a key set.
• keySetName—Specifies the name that uniquely identifies a key set.
Frequently used optional arguments:
• keySetScope—Specifies the management scope.
• keySetSaveConfig—Specifies true to automatically save the configuration23 without calling AdminConfig.save() after adding the key reference, false to save to the configuration with a separate command.
23 This is the only method on any of the administrative scripting objects that has such a feature.
modifyKeySet
Modify the attributes of a key set.
Required argument:
• name—Specifies the name that uniquely identifies a key set.
Frequently used optional arguments:
• password—Specifies the password for the key.
• keyStoreName—Specifies the unique name to identify the keystore.
• aliasPrefix—Specifies the key alias prefix name.
• maxKeyReferences—Specifies the maximum number of keys stored.
• sKeyPair—Specifies true if the key set is a key pair, false otherwise.
• deleteOldKeys—Specifies true to delete old keys during key generation, false to retain old keys.
• scopeName—Specifies the management scope.
• keyStoreScopeName—Specifies the management scope of the keystore.
• keyGenerationClass—Specifies the class used to generate keys.
PolicySetManagement Group
Policies are a very important component of WebSphere Application Server V7 architecture. See Web Service Policy Sets section earlier in the chapter Web Service Policy Sets for details.
addPolicyType
The addPolicyType command creates a policy type with default values for the specified policy set. You may indicate whether to enable or disable the added policy type.
• policyType—Specifies the name of the policy to add to the policy set.
• policySet—Specifies the policy set name.
Frequently used optional argument:
• enabled—If this parameter is set to true, the new policy type is enabled in the policy set. If this parameter is set to false, the configuration is contained within the policy set, but the configuration does not have an effect on the system.
createPolicySet
The createPolicySet command creates a new policy set. Policy types are not created with the policy set. The default indicator is set to false.
Required argument:
• policySet—Specifies the name of this policySet.
Frequently used optional arguments:
• description—Adds a description for the policy set.
• policySetType—Specifies the type of policy set. The type must already exist.
createPolicySetAttachment
Creates a new policy set attachment. This method returns a value; specifically it returns an attachment ID. You will need that when attaching a binding for the policy. You have two choices: You can either assign it to a value at invocation time, or you can attempt to locate it later, using AdminTask.getPolicySetAttachments().24
24 See AdminTask.getPolicySetAttachments() for details.
Required arguments:
• policySet—Specifies the policy set name. The policySet must already exist.
• resources—Specifies the names of the application or trust service resources.
Frequently used optional arguments:
• applicationName—Specifies the name of the application. This parameter applies to application and client attachments. It is not applicable to trust service attachments.
• attachmentType—Specifies the type of policy set attachments. The value for this parameter must be application, client, or system/trust. The default value is application.
• dynamicClient—Indicates that the client resources should not be validated. The default value for this parameter is false.
• attachmentProperties—The attachment-specific properties.
listPolicyTypes
Returns a list of the names of the policies configured in the system, in a policy set, or in a binding. The arguments are optional. They serve to limit the scope of the policy types that are returned.
Frequently used optional arguments:
• policySet—Specifies the policy set name. For a list of all policy set names, use the listPolicySets command.
• attachmentType—Specifies the type of policy set attachments. The value for this parameter must be application, client, or system/trust. The default value is application.
• bindingName—Specifies the name for the binding. The binding name is optional when you are creating a new binding. A name is generated if it is not specified. The binding name is required when you are changing an attachment to use a different existing binding.
• fromDefaultRepository—Indicates if the command should use the default repository.
• enabled—If this parameter is set to true, only the policy types that are enabled in the policy set are listed. If this parameter is set to false, all of the policy types in the policy set are listed.
listPolicySets
Returns a list of all existing policy sets. The arguments are optional. They serve to limit the scope of the policy sets that are returned.
Frequently used optional argument:
• policySetType—Specifies the type of policy set. Specify application to list application policy sets. Specify system/trust to list the trust service policy sets. The default value for this parameter is application.
• fromDefaultRepository—Indicates if the command should use the default repository.
listAttachmentsForPolicySet
Lists the applications to which a specific policy set is attached.
Required argument:
• policySet—Specifies the policy set name. The policySet must already exist.
Frequently used optional argument:
• attachmentType—Specifies the type of policy set attachments. The value for this parameter must be application, client, or system/trust. The default value is application.
listAssetsAttachedToPolicySet
Lists the assets to which a specific policy set is attached.
Required argument:
• policySet—Specifies the policy set name. The policySet must already exist.
Frequently used optional argument:
• attachmentType—Specifies the type of policy set attachments. The value for this parameter must be application, client, or system/trust. The default value is application.
getPolicySet
Returns general attributes, such as description and default indicator, for the specified policy set.
Required argument:
• policySet—Specifies the policy set name. For a list of all policy set names, use the AdminTask.listPolicySets().
Frequently used optional argument:
• fromDefaultRepository—Indicates if the command should use the default repository. Set this argument to true to use the default repository. Set it to false or omit it entirely if you do not wish to use the default repository.
getPolicyType
Returns the attributes for a specified policy.
Required arguments:
• policySet—Specifies the policy set name.
• policyType—Specifies the name of the policy to add to the policy set. The name you pass must be one of the types returned by calling some form of the AdminTask.listPolicySets() command.25
25 See AdminTask.listPolicySets() for details.
Frequently used optional arguments:
• attributes—Specifies the attributes to display. If this parameter is used, the command returns all attributes for the specified policy type as an array of strings.
• fromDefaultRepository—Indicates if the command should use the default repository. Set this argument to true to use the default repository. Set it to false or omit it entirely if you do not wish to use the default repository.
getPolicySetAttachments
Lists the properties for all attachments configured for a specified application, client, or for the trust service. All arguments here are optional; however, it is not possible to call this method without arguments. See arguments for details.
Frequently used optional arguments:
• applicationName—Specifies the name of the application. This parameter applies to application and client attachments. It is not applicable to system/trust service attachments. You may not specify this argument for system/trust service attachments.
• attachmentType—Specifies the type of policy set attachments. The value for this parameter must be application, client, or system/trust. The default value is application.
• expandResources—Provides expanded information that details the attachment properties for each resource. An asterisk (*) character returns all Web services.
• attachmentProperties—The attachment-specific properties. This must be some value that can be converted into a java.util.Properties object.
getBinding
Returns the binding configuration for a specified policy type and scope.
Frequently used optional arguments:
• bindingName—Specifies the name for the binding. The binding name is optional when you are creating a new binding. A name is generated if it is not specified. The binding name is required when you are changing an attachment to use a different existing binding.
• policyType—Specifies the name of the policy to add to the policy set. The name you pass must be one of the types returned by calling some form of the AdminTask.listPolicySets() command.26
26 See listPolicySets for details.
• attributes—Specifies the attribute values to update. If the attributes parameter is not specified, the command only updates the binding location used by the specified attachment. Any value you pass here must be convertible into a java.util.Properties object.
• attachmentType—Specifies the type of policy set attachments. The value for this parameter must be application, client, or system/trust. The default value is application.
getDefaultBindings
Returns the default binding names for a specified domain or server.
Frequently used optional argument:
• domainName—Specifies the name of the domain. The domain name is only required when the domain is not the global security domain.
getRequiredBindingVersion
Returns the binding version that is required for a specified asset.
Required argument:
• assetProps—Specifies the asset, such as the application name.
importPolicySet
Imports a policy set from a compressed archive onto a server environment. A side-effect of the existence of this method is that you can create policies in one of several ways. You can manipulate the various parts of a policy with methods in this group, or you can edit XML files in a text editor and import the complete set of XML files that make up a given policy.
Frequently used optional arguments:
• importFile—Specifies the path name of the archive file to import.
• defaultPolicySet—The name of the default policy set to import.
• policySet—Specifies the policy set name. For a list of all policy set names, use the listPolicySets command.
• verifyPolicySetType—Verifies the policy set is of this type.
exportPolicySet
Exports a policy set as an archive that can be copied onto a client environment or imported onto a server environment. A side-effect of the existence of this method is that you can create policies in one of several ways. You can manipulate the various parts of a policy with methods in this group, or you can edit XML files in a text editor and import the complete set of XML files that make up a given policy.
Required arguments:
• policySet—Specifies the policy set name. The policySet must already exist.
• pathName—Specifies the path name of the archive file. It is recommended that you pass a fully qualified file name. Regardless of the operating system that you use, you should use a forward slash as a directory delimiter.
copyPolicySet
Creates a copy of an existing policy set. The default indicator is set to false for the new policy set. You can indicate whether to transfer attachments from the existing policy set to the new policy set.
Required arguments:
• sourcePolicySet—Specifies the name of the existing policy set.
• newPolicySet—Specifies the name of the new policy set.
Frequently used optional arguments:
• newDescription—Adds a description for the policy set or binding.
• transferAttachments—If this parameter is set to true, all attachments transfer from the source policy set to the new policy set. The default value is false.
validatePolicySet
Validates the policies in the policy set.
Required argument:
• policySet—Specifies the policy set name. For a list of all policy set names, use the listPolicySets command.
importBinding
Imports a binding from a compressed archive onto a server environment. A side-effect of the existence of this method is that you can create bindings in one of several ways. You can manipulate the various parts of a binding with methods in this group, or you can edit XML files in a text editor and import the complete set of XML files that make up a given binding.
Required argument:
• importFile—Specifies the path name of the archive file to import. It is recommended that you pass a fully qualified file name. Regardless of the operating system that you use, you should use a forward slash as a directory delimiter.
Frequently used optional arguments:
• bindingName—Specifies the name for the binding. The binding name is optional when you are creating a new binding. A name is generated if it is not specified. The binding name is required when you are changing an attachment to use a different existing binding.
• verifyBindingType—Verifies the binding is of this type. It is recommended that you set this optional argument to true.
• domainName—Specifies the name of the domain. The domain name is only required when the domain27 is not the global security domain.
27 See Chapter 12, “Scripting and Security,” for additional information about security domains.
exportBinding
Exports a binding as an archive that can be copied onto a client environment or imported onto a server environment. A side-effect of the existence of this method is that you can create bindings in one of several ways. You can manipulate the various parts of a binding with methods in this group, or you can edit XML files in a text editor and import the complete set of XML files that make up a given binding.
Required arguments:
• bindingName—Specifies the name for the binding. The binding name is optional when you are creating a new binding. A name is generated if it is not specified. The binding name is required when you are changing an attachment to use a different existing binding.
• pathName—Specifies the path name of the archive file. It is recommended that you pass a fully qualified file name. Regardless of the operating system that you use, you should use a forward slash as a directory delimiter.
copyBinding
Creates a copy of an existing binding.
Required arguments:
• sourceBinding—Specifies the name of the existing binding.
• newBinding—Specifies the name of the binding to which the bindings are copied.
Frequently used optional arguments:
• domainName—Specifies the name of the domain. The domain name is required when newBinding is part of a security domain. This argument is not required when newBinding is part of the global security domain.
• newDescription—Adds a description for newBinding.
setBinding
Updates the binding configuration for a specified policy type and scope. Use this command to add a server-specific binding, update an attachment to use a custom binding, edit binding attributes, or remove a binding. Although strictly speaking, none of the arguments here are required, as a practical matter, you will find yourself passing bindingName very often.
Frequently used optional arguments:
• bindingName—Specifies the name for the binding. The binding name is optional when you are creating a new binding. A name is generated if it is not specified. The binding name is required when you are changing an attachment to use a different existing binding.
• bindingScope—Specifies the scope of the binding. The binding scope is only required when you are changing an attachment to use an existing named binding or when you are removing a named binding from an attachment.
• attachmentType—Specifies the type of policy set attachments. The value for this parameter must be application, client, or system/trust. The default value is application.
• replace—If you set this value to true, the new attributes provided from the command replace the existing attributes. The default value is false.
• attributes28—Specifies the attribute values to update. If the attributes parameter is not specified, the command only updates the binding location used by the specified attachment.
28 The system will attempt to create a Java Properties object from whatever value you pass here. That means you must pass some Jython type that can be converted into a java.util.Properties object.
• policyType—Specifies the name of the policy to add to the policy set. This name must be one of the names returned by AdminTask.listPolicyTypes().29
29 See AdminTask.listPolicyTypes() in this chapter.
WebServicesAdmin Group
The methods in this group provide information about JAX-WS Web services provided by applications. The entire group is read-only. If you wish to change a JAX-WS Web service, you must edit the WSDL file using the AdminApp.edit() method. If you wish to view any details of a JAX-RPC Web service, you must examine the WSDL file.30 If you wish to change a JAX-RPC Web service, you must edit the deployment.31
30 See the AdminApp.publishWSDL() method description.
31 See AdminApp.edit() method and AdminApp.update() method as described in Chapter 10, “The AdminApp Object.”
listWebServices
This method lists the deployed Web services in enterprise applications. As of this writing, if there is no application name supplied, then all the Web services in the enterprise applications will are be listed.
Frequently used optional arguments:
• application—The deployed enterprise application name that contains Web services.
• client—Set true if you want client information about the service. Either set to false or omit it entirely to get server information about the service.
Steps:
1. J2EEWSStep—Lists the Web services.
listWebServiceEndpoints
Lists the Web service endpoints that are port names defined in a Web service in an enterprise application.
Required arguments:
• application—The enterprise application name that contains the Web service(s).
• module—The module name within the aforementioned application that contains the Web service(s).
• service—The Web service name within the aforementioned module whose attributes you want.
Frequently used optional argument:
• client—Set to true if you want client information about the service. Either set to false or omit it entirely to get server information about the service.
Steps
1. J2EEWSStep—Lists the logical endpoints that are port names in a Web service.
listWebServiceOperations
Lists the Web service endpoints that are port names defined in a Web service in an enterprise application.
Required arguments:
• application—The enterprise application name that contains the Web service(s).
• module—The module name within the aforementioned application that contains the Web service(s).
• service—The Web service name within the aforementioned module whose attributes you want.
• logicalEndpoint—The name of the logical endpoint within the Web service within the aforementioned module whose attributes you want.
Frequently used optional argument:
• client—Set true if you want client information about the service. Either set false or omit it entirely to get server information about the service.
Steps:
1. J2EEWSStep—Lists the operations in a Web service endpoint.
getWebService
Gets the attributes for a given Web service in a given enterprise application.
Required arguments:
• application—The enterprise application name that contains the Web service(s).
• module—The module name within the aforementioned application that contains the Web service(s).
• service—The Web service name within the aforementioned module whose attributes you want.
Frequently used optional argument:
• client—Set to true if you want client information about the service. Either set it to false or omit it entirely to get server information about the service.
Steps:
1. J2EEWSStep—Lists the attributes for a Web service.
listServices
Lists the services based on generic query properties. It provides more generic query functions than listWebServices, listWebServiceEndpoints, listWebServiceOperations, and getWebService commands.
Frequently used optional arguments:
• queryProps—The query properties for services.
• expandResource—Expand endpoint or operation resource in the service.