Cover image for Java Web Services in a Nutshell

Book description

Java Web Services in a Nutshell is a high-speed tutorial and a quick reference for the technologies that Sun Microsystems is creating for implementing web services with Java. This book is a succinct introduction and handy reference to the Java/XML APIs, more commonly known as the JWSDP or "Java Web Services Development Pack." These APIs are taking the Java world by storm, as they are capable of handling everything from simple XML to SOAP to full ebXML vocabularies. Although "web services" technology has suffered from much hype and overly grand expectations, there is plenty of solid development going on, especially in extending enterprise applications, and a huge amount of this development is being done in Java. As a result, the J2EE APIs for web services are evolving rapidly, and this new "in a Nutshell" book covers them all in depth. One of the most important APIs in the JWSDP is JAX-RPC (Java API for XML-based RPC). It's also the API that developers most consistently post questions about. Java Web Services in a Nutshell covers all aspects of JAX-RPC in detail, with tutorial coverage alone exceeding 150 pages. This book offers developers everything they need to program with JAX-RPC. Java Web Services in a Nutshell begins with an introduction to Java web services, including a discussion of how they differ from web applications. The author looks at the protocols and interfaces that underpin web services, the J2EE technologies that address web services, WSDL as the means for describe web services, and more. Subsequent chapters cover:

  • JAX-RPC

  • SOAP and the SOAP with Attachments API for Java (SAAJ)

  • Reliable SOAP messaging with JAXM

  • WSDL

  • Advanced JAX-RPC

  • JAXR, the XML-based registry API

  • Web Services Tools

The balance of the book is made up of an API Quick Reference containing documentation for the various API packages. Intended for Java developers who need to implement Java services or who need their applications to access existing web services, Java Web Services in a Nutshell delivers practical information to help developers make sense of the rapidly changing and poorly organized official documentation. If web services and Enterprise Java are any part of your job description -- of if you'd like them to be -- you'll want this book close beside as you work.

Table of Contents

  1. Java Web Services in a Nutshell
    1. Preface
      1. Contents of This Book
      2. Related Books
      3. Web Services Programming Resources Online
      4. Examples Online
        1. Installing the Example Source Code
          1. Tailoring the jwnutExamples.properties file
          2. Tailoring the jwsnutJaxrExamples.properties file
          3. Environment variables
        2. Using the Example Source Code with the JWSDP
        3. Using the Source Code with J2EE Version 1.4
        4. Using the Examples with a TCP Monitor Utility
      5. Conventions Used in This Book
      6. Request for Comments
      7. Acknowledgments
    2. I. Introduction to the Java Web Services API
      1. 1. Introduction
        1. What Is a Web Service?
          1. Web Services and Web Applications
        2. The SOAP Protocol
          1. Web Service Profiles
        3. Describing and Discovering Web Services
        4. J2EE Web Service APIs
        5. An Example Web Service
      2. 2. JAX-RPC
        1. JAX-RPC Overview
          1. The JAX-RPC Programming Model
            1. Services, ports, and bindings
            2. JAX-RPC web service clients and servers
            3. JAX-RPC service creation
            4. JAX-RPC client and server programming environments
            5. Stubs and ties
            6. Client invocation modes
          2. A Simple JAX-RPC Example
            1. Defining the service interface
            2. Implementing the service
            3. Writing the client code
            4. Example source code organization
            5. Compiling and running the book web service example
        2. Programming with JAX-RPC
          1. The JAX-RPC Service Interface
            1. Interface method definitions
            2. Supported data types
            3. Holder classes
            4. Value types
            5. Inner classes
            6. Other data types
          2. Converting the Service Interface Definition to Client-Side Stubs
          3. The Client-Side JAX-RPC API
          4. The Server-Side Implementation
            1. Server-side architecture
            2. Service implementation threading model
          5. Deployment of a JAX-RPC Service in a Web Container
          6. Deploying a JAX-RPC Service onto the J2EE 1.4 Platform
            1. Creating the portable WAR file
            2. Deploying the JAX-RPC service
          7. Deploying a JAX-RPC Service with the JWSDP
            1. Creating the portable WAR file
            2. Creating a deployable WAR file
            3. Deploying the service implementation
            4. Special handling for the HTTP GET request
            5. JWSDP configuration files and XML namespaces
        3. Using EJBs to Implement Web Services
          1. Web Service Session Bean Requirements
          2. EJB Web Service Programming Model
          3. The Book Web Service Implemented as a Stateless Session Bean
          4. EJB Web Service Deployment
          5. The EJB Web Service URL
      3. 3. SAAJ
        1. Introduction to SAAJ
        2. SAAJ Programming
        3. SOAP Messages
          1. Creating and Sending a SOAP Message Using SAAJ
          2. Receiving a SOAP Message
          3. The Anatomy of a SAAJ SOAP Message
            1. SOAPMessage
            2. SOAPPart
            3. SOAPEnvelope
            4. SOAPHeader
            5. SOAPBody
          4. Nodes, Elements, and Names
            1. Constructing the SOAP message to get the book titles
            2. Handling the BookList request in the service implementation
            3. Client processing for the reply to the BookList request
          5. More on SOAPElements
            1. Creation of SOAPElements
            2. Removal of SOAPElements
        4. SOAP Fault Handling
          1. Fault Codes
          2. Fault Actor
          3. Fault Details
          4. Creating Fault Elements
        5. SOAP Messages and MIME Headers
          1. The MimeHeader and MimeHeaders Classes
          2. Setting MIME Headers When a SOAP Message Is Transmitted
          3. Obtaining MIME Headers When a SOAP Message Is Received
        6. SOAP with Attachments
          1. An Example SOAP with Attachments Application
          2. Creating and Managing SOAP Attachments
          3. Attachment Headers and Content
            1. MIME headers
            2. Associating data with an AttachmentPart
            3. Specifying a value and a content type
            4. Using a DataHandler
          4. Processing Received Attachments
        7. SOAP Headers
          1. SOAP Actors and the mustUnderstand Attribute
          2. Creating Header Elements
          3. Processing Header Elements
        8. Using SAAJ with Secure Connections
          1. Using Basic Authentication
            1. Adding roles and users to the web container
            2. Adding URL-based protection
            3. Setting up the client
          2. Using HTTPS
            1. Enabling HTTPS in the web server
            2. Setting up the client system
      4. 4. JAXM
        1. JAXM Overview
          1. JAXM Message Delivery Modes
            1. Asynchronous inquiry
            2. Asynchronous update
            3. Fire-and-forget
        2. Providers and Asynchronous Messaging
          1. Provider Message Path
          2. The JAXM Execution Environment
        3. An Example JAXM Application
          1. Implementing the Sending Servlet for the JAXM Echo Service
            1. Servlet configuration
            2. Accessing the provider and creating the MessageFactory
            3. Handling requests from the browser
            4. Constructing and sending the message
            5. Handling the response message
          2. Implementing the Receiving Servlet for the JAXM Echo Service
          3. Why Synchronous Messaging Does Not Work with a Provider
        4. JAXM Configuration
          1. Configuring JAXM Clients
          2. Configuring the JAXM Provider
          3. How a Message Is Sent and Delivered
          4. Servlet Loading Issue
        5. The SOAP-RP Profile
          1. SOAP-RP Overview
          2. The JAXM SOAP-RP Message API
            1. Getting and setting the message ID
            2. Getting and updating the forward and reverse message paths
            3. Fault handling
        6. The ebXML Profile
          1. Overview of the ebXML Packaging Model
          2. The MessageHeader Element
          3. The Manifest Element
          4. An Example ebXML-TRP Message
          5. The JAXM ebXML Message API
            1. The ebXML MessageHeader element
            2. The ebXML Manifest element
      5. 5. WSDL
        1. WSDL Overview
        2. WSDL Elements
          1. The WSDL definitions Element
          2. Type Definitions
            1. Use of XML schema complexType and simpleType elements
            2. Use of XML schema element element
          3. Defining Messages
            1. Message names
            2. Message parts
          4. Port Types and Operations
            1. The portType element
            2. Operation elements
          5. Concrete Bindings
          6. The SOAP Binding
            1. The soap:binding and soap:operation elements
            2. Message construction elements
          7. The MIME Binding
          8. Ports and Services
          9. Using the import Element
            1. Importing types from an XML schema definition
            2. Separating WSDL definitions into separate files
      6. 6. Advanced JAX-RPC
        1. Using WSDL with JAX-RPC
          1. Stubs and One-Way Operations
        2. ServiceFactory and the Service Interface
          1. The ServiceFactory Class
          2. The Service Interface
          3. Using the getPort( ) Methods of a Generated Service Object
          4. Using getPort( ) with a Service Object from a ServiceFactory
        3. The Dynamic Invocation Interface
          1. Dynamic Invocation of a Service Defined by WSDL
          2. Dynamic Invocation of a Service Not Defined by WSDL
          3. DII and Exceptions
          4. One-Way Calls
          5. Call Object Properties
        4. JAX-RPC and J2EE 1.4 Application Clients
          1. Adding a Web Service Reference to the JNDI Environment
          2. Writing the J2EE Application Client
          3. Packaging and Deploying the Application Client
          4. Running the Application Client
          5. Web Service References for Servlets and EJBs
        5. Using Attachments
          1. Image Attachments
          2. DataHandler Attachments
          3. MimeMultipart Attachments
          4. XML Attachments
        6. RPC-Style and Document-Style JAX-RPC
          1. RPC-Style Operations
          2. Document-Style Operations
            1. JAX-RPC support for document-style operations
            2. JAX-RPC interface to document-style operations
            3. Implementing a service containing a document-style operation
            4. Suppressing the mapping of message content to method arguments
        7. Client and Server Context Handling
          1. The ServiceLifecycle Interface
          2. The ServletEndpointContext Interface
          3. Multithreaded Access to the ServletEndpointContext Object
          4. An Example Web Service Using ServletEndpointContext
          5. Session Management
          6. JAX-RPC Authentication
        8. SOAP Header Processing
          1. Mapping Header Content to Method Arguments
            1. Adding header parts to a service definition
            2. Generating the Java interface and client-side stubs
            3. Invoking the service
            4. The service implementation
          2. SOAP Message Handlers
            1. Message-handling architecture
            2. Message handler classes and interfaces
            3. Message handler configuration
            4. Headers, roles, and the mustUnderstand attribute
            5. A message handler example
            6. Initializing the HandlerRegistry when using dynamic proxies or dynamic invocation
        9. Serialization and Type Mappings
          1. Type Mappings and the Type Mapping Registry
          2. Initialization of the TypeMappingRegistry
          3. Adding Additional Serializers to the Registry
            1. Adding serializers to the client side
            2. Adding serializers to the server side
      7. 7. JAXR
        1. UDDI and ebXML Registries
        2. JAXR Architecture
        3. Using the JAXR Examples
          1. Using a UDDI Registry
            1. Edit the jwsnutJaxrExamples.properties file
            2. Start the registry server
            3. Install the sample registry data
          2. Using an ebXML Registry
            1. Create configuration files for the ebXML registry server
            2. Start the registry server
            3. Create a registry user
            4. Edit the jwsnutJaxrExamples.properties file
            5. Install the sample registry data
        4. JAXR Registry Model Overview
          1. Information Model Interfaces
          2. RegistryObject and RegistryEntry
          3. ExtensibleObject and Slots
            1. Application use of Slots
            2. Registry use of Slots
          4. Classification of Registry Objects
            1. External and internal classification schemes
            2. Concepts as enumerated types
        5. JAXR Programming
          1. Connecting to the Registry
          2. Retrieving Objects from the Registry
            1. Using QueryManager methods to retrieve registry objects
            2. Finding registry objects using BusinessQueryManager
            3. Searching by Classification
            4. Extended Classification searches
          3. Declarative Queries
          4. Asynchronous Queries
          5. Modifying the Registry
            1. Creating Organizations and Users
            2. Services, ServiceBindings, and SpecificationLinks
            3. Storing a WSDL document reference in an ebXML registry
            4. Storing a WSDL document reference in a UDDI registry
            5. Classifying registry objects
            6. Saving content in the registry
            7. Associations
          6. Creating User-Defined Classification Schemes and Enumerated Types
            1. Adding classification schemes to an ebXML provider
            2. Adding classification schemes to a UDDI provider
          7. Postal Addresses
            1. Creating a representation of a registry addressing scheme
            2. Mapping without a PostalAddress scheme
            3. Using the JAXR default PostalAddress scheme
            4. Using a different PostalAddress scheme
          8. Deleting Registry Objects
          9. Level 1 Registry Features
            1. ExtrinsicObjects
            2. RegistryPackages
            3. Object deprecation
            4. Auditing
          10. Registry Security
            1. Authorization
            2. Confidentiality
            3. User authentication
      8. 8. Web Service Tools and Configuration Files
        1. wscompile — JAX-RPC Stub and Tie Generation Utility
          1. Availability
          2. Synopsis
          3. Description
          4. Options
          5. Configuration File
            1. The service element
            2. The wsdl element
            3. The modelfile element
            4. The handlerChains element
            5. The typeMappingRegistry element
            6. The namespaceMappingRegistry element
          6. Generated Artifacts
          7. Features
        2. wsdeploy — JAX-RPC Deployable Web Archive Generation Utility
          1. Availability
          2. Synopsis
          3. Description
          4. Options
          5. Configuration File
            1. The endpoint element
            2. The endpointMapping element
          6. Target Web Archive File Content
            1. Original class files and resources
            2. Tie and serializer/deserializer classes
            3. Model file
            4. WSDL document
            5. Deployment descriptors
        3. J2EEC — Utility for Creating Stubs and Ties for a JAX-RPC Web Service
          1. Availability
          2. Synopsis
          3. Description
          4. Options
        4. J2EE Deploytool — Utility for Deploying Modules and Enterprise Applications
          1. Availability
          2. Synopsis
          3. Description
          4. Options
        5. JAXM Client and Provider Configuration
          1. Availability
          2. Description
          3. Provider Configuration
            1. Endpoint mappings
            2. Error handling
            3. Message persistence
          4. Client Application Configuration
        6. J2EE 1.4 Web Services Configuration File
          1. Availability
          2. Description
        7. J2EE 1.4 JAX-RPC Mapping File
          1. Availability
          2. Description
            1. Package mappings
    3. II. API Quick Reference
      1. 9. The javax.xml.messaging Package
        1. Package javax.xml.messaging
        2. Endpoint
        3. JAXMException
        4. JAXMServlet
        5. OnewayListener
        6. ProviderConnection
        7. ProviderConnectionFactory
        8. ProviderMetaData
        9. ReqRespListener
        10. URLEndpoint
      2. 10. The javax.xml.namespace Package
        1. Package javax.xml.namespace
        2. QName
      3. 11. The javax.xml.registry Package
        1. Package javax.xml.registry
        2. BulkResponse
        3. BusinessLifeCycleManager
        4. BusinessQueryManager
        5. CapabilityProfile
        6. Connection
        7. ConnectionFactory
        8. DeclarativeQueryManager
        9. DeleteException
        10. FederatedConnection
        11. FindException
        12. FindQualifier
        13. InvalidRequestException
        14. JAXRException
        15. JAXRResponse
        16. LifeCycleManager
        17. Query
        18. QueryManager
        19. RegistryException
        20. RegistryService
        21. SaveException
        22. UnexpectedObjectException
        23. UnsupportedCapabilityException
      4. 12. The javax.xml.registry.infomodel Package
        1. Package javax.xml.registry.infomodel
        2. Association
        3. AuditableEvent
        4. Classification
        5. ClassificationScheme
        6. Concept
        7. EmailAddress
        8. ExtensibleObject
        9. ExternalIdentifier
        10. ExternalLink
        11. ExtrinsicObject
        12. InternationalString
        13. Key
        14. LocalizedString
        15. Organization
        16. PersonName
        17. PostalAddress
        18. RegistryEntry
        19. RegistryObject
        20. RegistryPackage
        21. Service
        22. ServiceBinding
        23. Slot
        24. SpecificationLink
        25. TelephoneNumber
        26. URIValidator
        27. User
        28. Versionable
      5. 13. The javax.xml.rpc Package
        1. Package javax.xml.rpc
        2. Call
        3. JAXRPCException
        4. NamespaceConstants
        5. ParameterMode
        6. Service
        7. ServiceException
        8. ServiceFactory
        9. Stub
      6. 14. The javax.xml.rpc.encoding Package
        1. Package javax.xml.rpc.encoding
        2. DeserializationContext
        3. Deserializer
        4. DeserializerFactory
        5. SerializationContext
        6. Serializer
        7. SerializerFactory
        8. TypeMapping
        9. TypeMappingRegistry
        10. XMLType
      7. 15. The javax.xml.rpc.handler Package
        1. Package javax.xml.rpc.handler
        2. GenericHandler
        3. Handler
        4. HandlerChain
        5. HandlerInfo
        6. HandlerRegistry
        7. MessageContext
      8. 16. The javax.xml.rpc.handler.soap Package
        1. Package javax.xml.rpc.handler.soap
        2. SOAPMessageContext
      9. 17. The javax.xml.rpc.holders Package
        1. Package javax.xml.rpc.holders
        2. BigDecimalHolder
        3. BigIntegerHolder
        4. BooleanHolder
        5. BooleanWrapperHolder
        6. ByteArrayHolder
        7. ByteHolder
        8. ByteWrapperHolder
        9. CalendarHolder
        10. DoubleHolder
        11. DoubleWrapperHolder
        12. FloatHolder
        13. FloatWrapperHolder
        14. Holder
        15. IntegerWrapperHolder
        16. IntHolder
        17. LongHolder
        18. LongWrapperHolder
        19. ObjectHolder
        20. QNameHolder
        21. ShortHolder
        22. ShortWrapperHolder
        23. StringHolder
      10. 18. The javax.xml.rpc.server Package
        1. Package javax.xml.rpc.server
        2. ServiceLifecycle
        3. ServletEndpointContext
      11. 19. The javax.xml.rpc.soap Package
        1. Package javax.xml.rpc.soap
        2. SOAPFaultException
      12. 20. The javax.xml.soap Package
        1. Package javax.xml.soap
        2. AttachmentPart
        3. Detail
        4. DetailEntry
        5. MessageFactory
        6. MimeHeader
        7. MimeHeaders
        8. Name
        9. Node
        10. SOAPBody
        11. SOAPBodyElement
        12. SOAPConnection
        13. SOAPConnectionFactory
        14. SOAPConstants
        15. SOAPElement
        16. SOAPElementFactory
        17. SOAPEnvelope
        18. SOAPException
        19. SOAPFactory
        20. SOAPFault
        21. SOAPFaultElement
        22. SOAPHeader
        23. SOAPHeaderElement
        24. SOAPMessage
        25. SOAPPart
        26. Text
      13. 21. Class, Method, and Field Index
        1. A-G
        2. H-X
    4. III. Appendix
      1. A. Appendix: WSDL Files for the Example Source Code
        1. WSDL File for the Book Web Service
        2. WSDL File for the Document-Style Book Web Service
    5. Index
    6. Colophon