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.wsdl.writer;
  27 
  28 import com.sun.istack.internal.NotNull;
  29 import com.sun.xml.internal.txw2.TypedXmlWriter;
  30 import com.sun.xml.internal.ws.api.WSBinding;
  31 import com.sun.xml.internal.ws.api.model.CheckedException;
  32 import com.sun.xml.internal.ws.api.model.JavaMethod;
  33 import com.sun.xml.internal.ws.api.model.SEIModel;
  34 import com.sun.xml.internal.ws.api.server.Container;
  35 import com.sun.xml.internal.ws.api.server.WSEndpoint;
  36 
  37 /**
  38  * This is a callback interface used to extend the WSDLGenerator.  Implementors
  39  * of this interface can add their own WSDL extensions to the generated WSDL.
  40  * There are a number of methods that will be invoked allowing the extensions
  41  * to be generated on various WSDL elements.
  42  * <p/>
  43  * The JAX-WS WSDLGenerator uses TXW to serialize the WSDL out to XML.
  44  * More information about TXW can be located at
  45  * <a href="http://txw.dev.java.net">http://txw.dev.java.net</a>.
  46  */
  47 public abstract class WSDLGeneratorExtension {
  48     /**
  49      * Called at the very beginning of the process.
  50      * <p/>
  51      * This method is invoked so that the root element can be manipulated before
  52      * any tags have been written. This allows to set e.g. namespace prefixes.
  53      * <p/>
  54      * Another purpose of this method is to let extensions know what model
  55      * we are generating a WSDL for.
  56      *
  57      * @param root      This is the root element of the generated WSDL.
  58      * @param model     WSDL is being generated from this {@link SEIModel}.
  59      * @param binding   The binding for which we generate WSDL. the binding {@link WSBinding} represents a particular
  60      *                  configuration of JAXWS. This can be typically be overriden by
  61      * @param container The entry point to the external environment.
  62      *                  If this extension is used at the runtime to generate WSDL, you get a {@link Container}
  63      *                  that was given to {@link WSEndpoint#create}.
  64      *                  TODO: think about tool side
  65      * @deprecated
  66      */
  67     public void start(@NotNull TypedXmlWriter root, @NotNull SEIModel model, @NotNull WSBinding binding, @NotNull Container container) {
  68     }
  69 
  70     /**
  71      * Called before writing </wsdl:defintions>.
  72      *
  73      * @param ctxt
  74      */
  75     public void end(@NotNull WSDLGenExtnContext ctxt) {
  76     }
  77 
  78     /**
  79      * Called at the very beginning of the process.
  80      * <p/>
  81      * This method is invoked so that the root element can be manipulated before
  82      * any tags have been written. This allows to set e.g. namespace prefixes.
  83      * <p/>
  84      * Another purpose of this method is to let extensions know what model
  85      * we are generating a WSDL for.
  86      *
  87      * @param ctxt Provides the context for the generator extensions
  88      */
  89     public void start(WSDLGenExtnContext ctxt) {
  90     }
  91 
  92     /**
  93      * This method is invoked so that extensions to a <code>wsdl:definitions</code>
  94      * element can be generated.
  95      *
  96      * @param definitions This is the <code>wsdl:defintions</code> element that the extension can be added to.
  97      */
  98     public void addDefinitionsExtension(TypedXmlWriter definitions) {
  99     }
 100 
 101     /**
 102      * This method is invoked so that extensions to a <code>wsdl:service</code>
 103      * element can be generated.
 104      *
 105      * @param service This is the <code>wsdl:service</code> element that the extension can be added to.
 106      */
 107     public void addServiceExtension(TypedXmlWriter service) {
 108     }
 109 
 110     /**
 111      * This method is invoked so that extensions to a <code>wsdl:port</code>
 112      * element can be generated.
 113      *
 114      * @param port This is the wsdl:port element that the extension can be added to.
 115      */
 116     public void addPortExtension(TypedXmlWriter port) {
 117     }
 118 
 119     /**
 120      * This method is invoked so that extensions to a <code>wsdl:portType</code>
 121      * element can be generated.
 122      * <p/>
 123      *
 124      * @param portType This is the wsdl:portType element that the extension can be added to.
 125      */
 126     public void addPortTypeExtension(TypedXmlWriter portType) {
 127     }
 128 
 129     /**
 130      * This method is invoked so that extensions to a <code>wsdl:binding</code>
 131      * element can be generated.
 132      * <p/>
 133      * <p/>
 134      * TODO:  Some other information may need to be passed
 135      *
 136      * @param binding This is the wsdl:binding element that the extension can be added to.
 137      */
 138     public void addBindingExtension(TypedXmlWriter binding) {
 139     }
 140 
 141     /**
 142      * This method is invoked so that extensions to a <code>wsdl:portType/wsdl:operation</code>
 143      * element can be generated.
 144      *
 145      * @param operation This is the wsdl:portType/wsdl:operation  element that the
 146      *                  extension can be added to.
 147      * @param method    {@link JavaMethod} which captures all the information to generate wsdl:portType/wsdl:operation
 148      */
 149     public void addOperationExtension(TypedXmlWriter operation, JavaMethod method) {
 150     }
 151 
 152 
 153     /**
 154      * This method is invoked so that extensions to a <code>wsdl:binding/wsdl:operation</code>
 155      * element can be generated.
 156      *
 157      * @param operation This is the wsdl:binding/wsdl:operation  element that the
 158      *                  extension can be added to.
 159      * @param method    {@link JavaMethod} which captures all the information to generate wsdl:portType/wsdl:operation
 160      */
 161     public void addBindingOperationExtension(TypedXmlWriter operation, JavaMethod method) {
 162     }
 163 
 164     /**
 165      * This method is invoked so that extensions to an input <code>wsdl:message</code>
 166      * element can be generated.
 167      *
 168      * @param message This is the input wsdl:message element that the
 169      *                extension can be added to.
 170      * @param method  {@link JavaMethod} which captures all the information to generate wsdl:portType/wsdl:operation
 171      */
 172     public void addInputMessageExtension(TypedXmlWriter message, JavaMethod method) {
 173     }
 174 
 175     /**
 176      * This method is invoked so that extensions to an output <code>wsdl:message</code>
 177      * element can be generated.
 178      *
 179      * @param message This is the output wsdl:message element that the
 180      *                extension can be added to.
 181      * @param method  {@link JavaMethod} which captures all the information to generate wsdl:portType/wsdl:operation
 182      */
 183     public void addOutputMessageExtension(TypedXmlWriter message, JavaMethod method) {
 184     }
 185 
 186 
 187     /**
 188      * This method is invoked so that extensions to a
 189      * <code>wsdl:portType/wsdl:operation/wsdl:input</code>
 190      * element can be generated.
 191      *
 192      * @param input  This is the wsdl:portType/wsdl:operation/wsdl:input  element that the
 193      *               extension can be added to.
 194      * @param method {@link JavaMethod} which captures all the information to generate wsdl:portType/wsdl:operation
 195      */
 196     public void addOperationInputExtension(TypedXmlWriter input, JavaMethod method) {
 197     }
 198 
 199 
 200     /**
 201      * This method is invoked so that extensions to a <code>wsdl:portType/wsdl:operation/wsdl:output</code>
 202      * element can be generated.
 203      *
 204      * @param output This is the wsdl:portType/wsdl:operation/wsdl:output  element that the
 205      *               extension can be added to.
 206      * @param method {@link JavaMethod} which captures all the information to generate wsdl:portType/wsdl:operation
 207      */
 208     public void addOperationOutputExtension(TypedXmlWriter output, JavaMethod method) {
 209     }
 210 
 211     /**
 212      * This method is invoked so that extensions to a
 213      * <code>wsdl:binding/wsdl:operation/wsdl:input</code>
 214      * element can be generated.
 215      *
 216      * @param input  This is the wsdl:binding/wsdl:operation/wsdl:input  element that the
 217      *               extension can be added to.
 218      * @param method {@link JavaMethod} which captures all the information to generate wsdl:portType/wsdl:operation
 219      */
 220     public void addBindingOperationInputExtension(TypedXmlWriter input, JavaMethod method) {
 221     }
 222 
 223 
 224     /**
 225      * This method is invoked so that extensions to a  <code>wsdl:binding/wsdl:operation/wsdl:output</code>
 226      * element can be generated.
 227      *
 228      * @param output This is the wsdl:binding/wsdl:operation/wsdl:output  element that the
 229      *               extension can be added to.
 230      * @param method {@link JavaMethod} which captures all the information to generate wsdl:portType/wsdl:operation
 231      */
 232     public void addBindingOperationOutputExtension(TypedXmlWriter output, JavaMethod method) {
 233     }
 234 
 235     /**
 236      * This method is invoked so that extensions to a <code>wsdl:binding/wsdl:operation/wsdl:fault</code>
 237      * element can be generated.
 238      *
 239      * @param fault  This is the wsdl:binding/wsdl:operation/wsdl:fault or wsdl:portType/wsdl:output/wsdl:operation/wsdl:fault
 240      *               element that the extension can be added to.
 241      * @param method {@link JavaMethod} which captures all the information to generate wsdl:portType/wsdl:operation
 242      */
 243     public void addBindingOperationFaultExtension(TypedXmlWriter fault, JavaMethod method, CheckedException ce) {
 244     }
 245 
 246     /**
 247      * This method is invoked so that extensions to a <code>wsdl:portType/wsdl:operation/wsdl:fault</code>
 248      * element can be generated.
 249      *
 250      * @param message This is the fault wsdl:message element that the
 251      *                extension can be added to.
 252      * @param method  {@link JavaMethod} which captures all the information to generate wsdl:portType/wsdl:operation
 253      *
 254      * @param ce      {@link CheckedException} that abstracts wsdl:fault
 255      */
 256     public void addFaultMessageExtension(TypedXmlWriter message, JavaMethod method, CheckedException ce) {
 257     }
 258 
 259     /**
 260      * This method is invoked so that extensions to a <code>wsdl:portType/wsdl:operation/wsdl:fault</code>
 261      * element can be generated.
 262      *
 263      * @param fault  This is the wsdl:portType/wsdl:operation/wsdl:fault  element that the
 264      *               extension can be added to.
 265      * @param method {@link JavaMethod} which captures all the information to generate wsdl:portType/wsdl:operation
 266      * @param ce     {@link CheckedException} that abstracts wsdl:fault
 267      */
 268     public void addOperationFaultExtension(TypedXmlWriter fault, JavaMethod method, CheckedException ce) {
 269     }
 270 
 271 }