001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: package org.apache.axis2.jaxws.message;
020:
021: import org.apache.axiom.om.OMElement;
022: import org.apache.axis2.jaxws.message.factory.BlockFactory;
023:
024: import javax.jws.soap.SOAPBinding.Style;
025: import javax.xml.namespace.QName;
026: import javax.xml.soap.SOAPEnvelope;
027: import javax.xml.stream.XMLStreamException;
028: import javax.xml.stream.XMLStreamReader;
029: import javax.xml.stream.XMLStreamWriter;
030: import javax.xml.ws.WebServiceException;
031:
032: /**
033: * XMLPart
034: *
035: * The XML portion of a Message
036: *
037: * The JAX-WS implementation (proxy, message receiver, etc.) interact with the
038: * Message via Blocks. A Block is represented in the message as a root element tree
039: * in either the header, body or fault detail section. The Blocks can be easily
040: * decomposed into business objects (which are needed on the JAX-WS interfaces).
041: *
042: * In addition, the JAX-WS handler model requires that the XMLPart be exposed as
043: * an SAAJ SOAPEnvelope.
044: *
045: * The XMLPart abstraction hides the details of the message transformations from
046: * the JAX-WS implementation.
047: *
048: * @see org.apache.axis2.jaxws.message.Message
049: * @see org.apache.axis2.jaxws.message.Block
050: * @see org.apache.axis2.jaxws.message.impl.XMLPartBase for implementation details
051: *
052: */
053:
054: /** @author scheu */
055: public interface XMLPart {
056:
057: /**
058: * Get the protocol for this Message (soap11, soap12, etc.)
059: *
060: * @return Protocl
061: */
062: public Protocol getProtocol();
063:
064: /**
065: * Write out the Message
066: *
067: * @param writer XMLStreamWriter
068: * @param consume true if this is the last request on the block.
069: * @throws WebServiceException
070: */
071: public void outputTo(XMLStreamWriter writer, boolean consume)
072: throws XMLStreamException, WebServiceException;
073:
074: /**
075: * Get the XMLStreamReader represented by this Message for the xml part
076: *
077: * @param consume true if this is the last request on the Message
078: * @return XMLStreamReader
079: * @throws WebServiceException
080: * @throws XMLStreamException
081: */
082: public XMLStreamReader getXMLStreamReader(boolean consume)
083: throws WebServiceException;
084:
085: /** @return the Style (document or rpc) */
086: public Style getStyle();
087:
088: /**
089: * Set the Style. If the style is DOCUMENT, the body blocks are located underneath the body
090: * element. If the style is set to RPC, then the body blocks are located underneath the rpc
091: * operation.
092: *
093: * @param style Style
094: * @see set indirection
095: */
096: public void setStyle(Style style) throws WebServiceException;
097:
098: /**
099: * Set indirection. Used to force the code to look for blocks at a particular location. For
100: * DOCUMENT the default is 0 For RPC the default is 1 This method is used to override these
101: * settings for special cases.
102: *
103: * @param indirection (0 or 1)
104: */
105: public void setIndirection(int indirection);
106:
107: /**
108: * Get indirection. Used to force the code to look for blocks at a particular location. For
109: * DOCUMENT the default is 0 For RPC the default is 1 This method is used to override these
110: * settings for special cases.
111: *
112: * @return indirection (0 or 1)
113: */
114: public int getIndirection();
115:
116: /** @return the QName of the operation element if Style.rpc. Otherwise null */
117: public QName getOperationElement() throws WebServiceException;
118:
119: /**
120: * Set the operation element qname. The operation qname is only used if Style.rpc
121: *
122: * @param operationQName
123: */
124: public void setOperationElement(QName operationQName)
125: throws WebServiceException;
126:
127: /**
128: * isConsumed Return true if the part is consumed. Once consumed, the information in the part is
129: * no longer available.
130: *
131: * @return true if the block is consumed (a method was called with consume=true)
132: */
133: public boolean isConsumed();
134:
135: /**
136: * Determines whether the XMLPart represents a Fault
137: *
138: * @return true if the message represents a fault
139: */
140: public boolean isFault() throws WebServiceException;
141:
142: /**
143: * If the XMLPart represents a fault, an XMLFault is returned which describes the fault in a
144: * protocol agnostic manner
145: *
146: * @return the XMLFault object or null
147: * @see XMLFault
148: */
149: public XMLFault getXMLFault() throws WebServiceException;
150:
151: /**
152: * Change the XMLPart so that it represents the fault described by XMLFault
153: *
154: * @param xmlfault
155: * @see XMLFault
156: */
157: public void setXMLFault(XMLFault xmlFault)
158: throws WebServiceException;
159:
160: /**
161: * getParent Get the Message object that this XMLPart is attached to, if it is attached to one
162: * at all.
163: *
164: * @return
165: */
166: public Message getParent();
167:
168: /**
169: * setParent Set the Message object that will hold this XMLPart
170: *
171: * @param m
172: */
173: public void setParent(Message m);
174:
175: /**
176: * getAsEnvelope Get the xml part as a read/write SOAPEnvelope
177: *
178: * @return SOAPEnvelope
179: * @throws WebServiceException
180: */
181: public SOAPEnvelope getAsSOAPEnvelope() throws WebServiceException;
182:
183: /**
184: * getAsOMElement Get the xml part as a read/write OM...note this returns an OM SOAPEnvelope for
185: * all protocols...even REST
186: *
187: * @return OMElement
188: * @throws WebServiceException
189: */
190: public OMElement getAsOMElement() throws WebServiceException;
191:
192: /**
193: * getNumBodyBlocks Calling this method will cache the OM. Avoid it in performant situations.
194: *
195: * @return number of body blocks
196: * @throws WebServiceException
197: */
198: public int getNumBodyBlocks() throws WebServiceException;
199:
200: /**
201: * getBodyBlock Get the body block at the specificed index. The BlockFactory and object context are
202: * passed in to help create the proper kind of block. Calling this method will cache the OM. Avoid
203: * it in performant situations.
204: *
205: * @param index
206: * @param context
207: * @param blockFactory
208: * @return Block or null
209: * @throws WebServiceException
210: * @see getBodyBlock
211: */
212: public Block getBodyBlock(int index, Object context,
213: BlockFactory blockFactory) throws WebServiceException;
214:
215: /**
216: * getBodyBlock Get the single Body Block. The BlockFactory and object context are passed in to
217: * help create the proper kind of block. This method should only be invoked when it is known
218: * that there is zero or one block.
219: *
220: * @param index
221: * @param context
222: * @param blockFactory
223: * @return Block or null
224: * @throws WebServiceException
225: */
226: public Block getBodyBlock(Object context, BlockFactory blockFactory)
227: throws WebServiceException;
228:
229: /**
230: * setBodyBlock Set the block at the specified index Once set, the Message owns the block. You
231: * must use the getBodyBlock method to access it.
232: *
233: * @param index
234: * @param block
235: * @throws WebServiceException
236: */
237: public void setBodyBlock(int index, Block block)
238: throws WebServiceException;
239:
240: /**
241: * setBodyBlock Set this as block as the single block for the message.
242: *
243: * @param index
244: * @param block
245: * @throws WebServiceException
246: */
247: public void setBodyBlock(Block block) throws WebServiceException;
248:
249: /**
250: * removeBodyBlock Removes the indicated BodyBlock
251: *
252: * @param index
253: * @throws WebServiceException
254: */
255: public void removeBodyBlock(int index) throws WebServiceException;
256:
257: /**
258: * getNumHeaderBlocks
259: *
260: * @return number of header blocks
261: * @throws WebServiceException
262: */
263: public int getNumHeaderBlocks() throws WebServiceException;
264:
265: /**
266: * getHeaderBlock Get the header block with the specified name The BlockFactory and object context
267: * are passed in to help create the proper kind of block.
268: *
269: * @param namespace
270: * @param localPart
271: * @param context
272: * @param blockFactory
273: * @return Block
274: * @throws WebServiceException
275: */
276: public Block getHeaderBlock(String namespace, String localPart,
277: Object context, BlockFactory blockFactory)
278: throws WebServiceException;
279:
280: /**
281: * appendHeaderBlock Append the block to the list of header blocks. The Message owns the block.
282: * You must use the getHeaderBlock method to access it.
283: *
284: * @param namespace
285: * @param localPart
286: * @param block
287: * @throws WebServiceException
288: */
289: public void setHeaderBlock(String namespace, String localPart,
290: Block block) throws WebServiceException;
291:
292: /**
293: * removePayload Removes the indicated block
294: *
295: * @param namespace
296: * @param localPart
297: * @throws WebServiceException
298: */
299: public void removeHeaderBlock(String namespace, String localPart)
300: throws WebServiceException;
301:
302: /**
303: * Get a traceString...the trace string dumps the contents of the Block without forcing an
304: * underlying ill-performant transformation of the message.
305: *
306: * @return String containing trace information
307: * @boolean indent String containing indent characters
308: */
309: public String traceString(String indent);
310:
311: /**
312: * The representation of the XMLPart may be in a number of different forms. Currently the forms
313: * are UNKNOWN, OM, SOAPENVELOPE, and SPINE. This method returns a String containing one of
314: * these types. This method should only be used for trace and testing purposes. The consumer
315: * of a Message should not make any decisions based on the representation of the XMLPart
316: *
317: * @return String
318: */
319: public String getXMLPartContentType();
320: }
|