View Javadoc
1   /*
2    * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package com.sun.xml.internal.ws.api.server;
27  
28  import com.sun.istack.internal.Nullable;
29  import javax.xml.stream.XMLStreamWriter;
30  import javax.xml.stream.XMLStreamException;
31  import javax.xml.namespace.QName;
32  import java.io.OutputStream;
33  import java.io.IOException;
34  import java.net.URL;
35  import java.util.Set;
36  
37  import com.sun.org.glassfish.gmbal.ManagedAttribute;
38  import com.sun.org.glassfish.gmbal.ManagedData;
39  
40  /**
41   * Represents an individual document that forms a {@link ServiceDefinition}.
42   *
43   * <pre>
44   * TODO:
45   *      how does those documents refer to each other?
46   *
47   * </pre>
48   *
49   * @author Jitendra Kotamraju
50   */
51  @ManagedData
52  public interface SDDocument {
53  
54      /**
55       * Gets the root tag name of this document.
56       *
57       * <p>
58       * This can be used to identify a kind of document quickly
59       * (such as schema, WSDL, ...)
60       *
61       * @return
62       *      always non-null.
63       */
64      @ManagedAttribute
65      QName getRootName();
66  
67      /**
68       * Returns true if this document is WSDL.
69       */
70      @ManagedAttribute
71      boolean isWSDL();
72  
73      /**
74       * Returns true if this document is schema.
75       */
76      @ManagedAttribute
77      boolean isSchema();
78  
79      /**
80       * returns the referenced documents
81       */
82      @ManagedAttribute
83      Set<String> getImports();
84  
85      /**
86       * Gets the system ID of the document where it's taken from. Generated documents
87       * use a fake URL that can be used to resolve relative URLs. So donot use this URL
88       * for reading or writing.
89       */
90      @ManagedAttribute
91      URL getURL();
92  
93      /**
94       * Writes the document to the given {@link OutputStream}.
95       *
96       * <p>
97       * Since {@link ServiceDefinition} doesn't know which endpoint address
98       * {@link Adapter} is serving to, (and often it serves multiple URLs
99       * simultaneously), this method takes the PortAddressResolver as a parameter,
100      * so that it can produce the corret address information in the generated WSDL.
101      *
102      * @param portAddressResolver
103      *      An endpoint address resolver that gives endpoint address for a WSDL
104      *      port. Can be null.
105      * @param resolver
106      *      Used to resolve relative references among documents.
107      * @param os
108      *      The {@link OutputStream} that receives the generated document.
109      *
110      * @throws IOException
111      *      if there was a failure reported from the {@link OutputStream}.
112      */
113     void writeTo(@Nullable PortAddressResolver portAddressResolver,
114             DocumentAddressResolver resolver, OutputStream os) throws IOException;
115 
116     /**
117      * Writes the document to the given {@link XMLStreamWriter}.
118      *
119      * <p>
120      * The same as {@link #writeTo(PortAddressResolver,DocumentAddressResolver,OutputStream)} except
121      * it writes to an {@link XMLStreamWriter}.
122      *
123      * <p>
124      * The implementation must not call {@link XMLStreamWriter#writeStartDocument()}
125      * nor {@link XMLStreamWriter#writeEndDocument()}. Those are the caller's
126      * responsibility.
127      *
128      * @throws XMLStreamException
129      *      if the {@link XMLStreamWriter} reports an error.
130      */
131     void writeTo(PortAddressResolver portAddressResolver,
132             DocumentAddressResolver resolver, XMLStreamWriter out) throws XMLStreamException, IOException;
133 
134     /**
135      * {@link SDDocument} that represents an XML Schema.
136      */
137     interface Schema extends SDDocument {
138         /**
139          * Gets the target namepsace of this schema.
140          */
141         @ManagedAttribute
142         String getTargetNamespace();
143     }
144 
145     /**
146      * {@link SDDocument} that represents a WSDL.
147      */
148     interface WSDL extends SDDocument {
149         /**
150          * Gets the target namepsace of this schema.
151          */
152         @ManagedAttribute
153         String getTargetNamespace();
154 
155         /**
156          * This WSDL has a portType definition
157          * that matches what {@link WSEndpoint} is serving.
158          *
159          * TODO: does this info needs to be exposed?
160          */
161         @ManagedAttribute
162         boolean hasPortType();
163 
164         /**
165          * This WSDL has a service definition
166          * that matches the {@link WSEndpoint}.
167          *
168          * TODO: does this info need to be exposed?
169          */
170         @ManagedAttribute
171         boolean hasService();
172 
173         /**
174          * All &lt;service> names that were in this WSDL, or empty set if there was none.
175          * Used for error diagnostics.
176          */
177         @ManagedAttribute
178         Set<QName> getAllServices();
179     }
180 }