/* | |
* Copyright 2004,2005 The Apache Software Foundation. | |
* Copyright 2006 International Business Machines Corp. | |
* | |
* Licensed under the Apache License, Version 2.0 (the "License"); | |
* you may not use this file except in compliance with the License. | |
* You may obtain a copy of the License at | |
* | |
* http://www.apache.org/licenses/LICENSE-2.0 | |
* | |
* Unless required by applicable law or agreed to in writing, software | |
* distributed under the License is distributed on an "AS IS" BASIS, | |
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
* See the License for the specific language governing permissions and | |
* limitations under the License. | |
*/ | |
package org.apache.axis2.jaxws.message; | |
import javax.xml.namespace.QName; | |
import javax.xml.stream.XMLStreamException; | |
import javax.xml.stream.XMLStreamReader; | |
import javax.xml.stream.XMLStreamWriter; | |
import org.apache.axiom.om.OMElement; | |
import org.apache.axis2.jaxws.message.factory.BlockFactory; | |
/** | |
* Block | |
* A Block represents an xml element and associated sub-tree. | |
* The name of the element must be defined by a root element in a schema. | |
* All prefixes within the subtree must correspond to namespace declarations defined | |
* within the tree. | |
* Many specifications refer to this as a "embedded document" or "xml block". I chose | |
* the term, block, for simplicity. | |
* | |
* The block can be exposed as: | |
* * BusinessObject | |
* * StAX object | |
* | |
* Note that the whole Message can also be thought of as a Block. Thus a Message | |
* can be createFrom a Block and written as a Block. | |
* | |
* In addition, each of the accessors has a consume parameter. If | |
* consume is true, the Block is no longer valid after the message is called. | |
* (i.e. the implementation does not need to cache the information) | |
* | |
*/ | |
public interface Block { | |
/** | |
* Get a reference to the Business Object represented by this Block | |
* @param consume true if this is the last request on the block. | |
* @return Object (JAXB, String etc.) | |
* @throws XMLStreamException | |
* @throws MessageException | |
*/ | |
public Object getBusinessObject(boolean consume) throws XMLStreamException, MessageException; | |
/** | |
* GetBusinesContext | |
* Some business objects have an associated context object (i.e. JAXBContext) | |
* @return Context Object or null | |
*/ | |
public Object getBusinessContext(); | |
/** | |
* Get the XMLStreamReader represented by this Block | |
* @param consume true if this is the last request on the block. | |
* @return XMLStreamReader | |
* @throws XMLStreamException | |
*/ | |
public XMLStreamReader getXMLStreamReader(boolean consume) throws XMLStreamException, MessageException; | |
/** | |
* Get the OMElement represented by this Block. | |
* This call always consumes the block because you are taking control of the underlying OM | |
* @return | |
* @throws XMLStreamException | |
* @throws MessageException | |
*/ | |
public OMElement getOMElement() throws XMLStreamException, MessageException; | |
/** | |
* Write out the Block | |
* @param writer XMLStreamWriter | |
* @param consume true if this is the last request on the block. | |
* @throws XMLStreamException | |
* @trhows MessageException | |
*/ | |
public void outputTo(XMLStreamWriter writer, boolean consume) throws XMLStreamException, MessageException; | |
/** | |
* isConsumed | |
* Return true if the block is consumed. Once consumed, the information in the | |
* block is no longer available. | |
* @return true if the block is consumed (a method was called with consume=true) | |
*/ | |
public boolean isConsumed(); | |
/** | |
* Get a traceString...the trace string dumps the contents of the Block without forcing an underlying | |
* ill-performant transformation of the message. | |
* @boolean indent String containing indent characters | |
* @return String containing trace information | |
*/ | |
public String traceString(String indent); | |
/** | |
* @return If QName is available without doing an expensive parse of the business object, then return true | |
* Otherwise return false | |
* Note: This method should be used in situations where it would be nice to know the qname (like logging or a special check) | |
* but we don't want to cause an ill-performant parse. | |
*/ | |
public boolean isQNameAvailable(); | |
/** | |
* Get the QName (namespace, localpart) of the Block. Do not depend on prefix being set correctly. | |
* Asking for the QName can cause a performant hit. | |
* @see isQNameAvailable | |
* @return QName of the block | |
* @throw MessageException | |
*/ | |
public QName getQName() throws MessageException; | |
/** | |
* Get BlockFactory | |
* @return BlockFactory that created the Block | |
*/ | |
public BlockFactory getBlockFactory(); | |
/** | |
* Get the XMLPart that contains this Block, if it is attached to one at all. | |
* @return XMLPart that the Block is attached to | |
*/ | |
public XMLPart getParent(); | |
/** | |
* Set the XMLPart that will contain this Block. | |
*/ | |
public void setParent(XMLPart p); | |
} |