1/*
2 * Copyright (c) 1997, 2013, 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
26package com.sun.xml.internal.ws.api.server;
27
28import com.sun.istack.internal.Nullable;
29import javax.xml.stream.XMLStreamWriter;
30import javax.xml.stream.XMLStreamException;
31import javax.xml.namespace.QName;
32import java.io.OutputStream;
33import java.io.IOException;
34import java.net.URL;
35import java.util.Set;
36
37import com.sun.org.glassfish.gmbal.ManagedAttribute;
38import 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
52public 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}
181