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.OMDataSource;
022: import org.apache.axiom.om.OMElement;
023: import org.apache.axis2.jaxws.message.factory.BlockFactory;
024:
025: import javax.xml.namespace.QName;
026: import javax.xml.stream.XMLStreamException;
027: import javax.xml.stream.XMLStreamReader;
028: import javax.xml.stream.XMLStreamWriter;
029: import javax.xml.ws.WebServiceException;
030:
031: /**
032: * Block A Block represents an xml element and associated sub-tree. The name of the element must be
033: * defined by a root element in a schema. All prefixes within the subtree must correspond to
034: * namespace declarations defined within the tree. Many specifications refer to this as a "embedded
035: * document" or "xml block". I chose the term, block, for simplicity.
036: * <p/>
037: * The block can be exposed as: * BusinessObject * StAX object
038: * <p/>
039: * Note that the whole Message can also be thought of as a Block. Thus a Message can be createFrom
040: * a Block and written as a Block.
041: * <p/>
042: * In addition, each of the accessors has a consume parameter. If consume is true, the Block is no
043: * longer valid after the message is called. (i.e. the implementation does not need to cache the
044: * information)
045: */
046: public interface Block extends OMDataSource {
047:
048: /**
049: * Get a reference to the Business Object represented by this Block
050: *
051: * @param consume true if this is the last request on the block.
052: * @return Object (JAXB, String etc.)
053: * @throws XMLStreamException
054: * @throws WebServiceException
055: */
056: public Object getBusinessObject(boolean consume)
057: throws XMLStreamException, WebServiceException;
058:
059: /**
060: * GetBusinesContext Some business objects have an associated context object (i.e. JAXBContext)
061: *
062: * @return Context Object or null
063: */
064: public Object getBusinessContext();
065:
066: /**
067: * Get the XMLStreamReader represented by this Block
068: *
069: * @param consume true if this is the last request on the block.
070: * @return XMLStreamReader
071: * @throws XMLStreamException
072: */
073: public XMLStreamReader getXMLStreamReader(boolean consume)
074: throws XMLStreamException, WebServiceException;
075:
076: /**
077: * Get the OMElement represented by this Block. This call always consumes the block because you are
078: * taking control of the underlying OM
079: *
080: * @return
081: * @throws XMLStreamException
082: * @throws WebServiceException
083: */
084: public OMElement getOMElement() throws XMLStreamException,
085: WebServiceException;
086:
087: /**
088: * Write out the Block
089: *
090: * @param writer XMLStreamWriter
091: * @param consume true if this is the last request on the block.
092: * @throws XMLStreamException
093: * @trhows WebServiceException
094: */
095: public void outputTo(XMLStreamWriter writer, boolean consume)
096: throws XMLStreamException, WebServiceException;
097:
098: /**
099: * isConsumed Return true if the block is consumed. Once consumed, the information in the block
100: * is no longer available.
101: *
102: * @return true if the block is consumed (a method was called with consume=true)
103: */
104: public boolean isConsumed();
105:
106: /**
107: * Get a traceString...the trace string dumps the contents of the Block without forcing an
108: * underlying ill-performant transformation of the message.
109: *
110: * @return String containing trace information
111: * @boolean indent String containing indent characters
112: */
113: public String traceString(String indent);
114:
115: /**
116: * @return If QName is available without doing an expensive parse of the business object, then
117: * return true Otherwise return false Note: This method should be used in situations where
118: * it would be nice to know the qname (like logging or a special check) but we don't want
119: * to cause an ill-performant parse.
120: */
121: public boolean isQNameAvailable();
122:
123: /**
124: * Get the QName (namespace, localpart) of the Block. Do not depend on prefix being set correctly.
125: * Asking for the QName can cause a performant hit.
126: *
127: * @return QName of the block
128: * @throw WebServiceException
129: * @see isQNameAvailable
130: */
131: public QName getQName() throws WebServiceException;
132:
133: /**
134: * Get BlockFactory
135: *
136: * @return BlockFactory that created the Block
137: */
138: public BlockFactory getBlockFactory();
139:
140: /**
141: * Get the Message associated with this block
142: *
143: * @return Message
144: */
145: public Message getParent();
146:
147: /**
148: * Set the Message associated with this block (This method is intended to be called by the
149: * Message Implementation only)
150: *
151: * @param parent
152: */
153: public void setParent(Message parent);
154:
155: /**
156: * @return true if data is always an element; false if possibly mixed content or multiple
157: * elements
158: */
159: public boolean isElementData();
160: }
|