| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you 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 org.apache.axiom.om.OMDataSourceExt; |
| import org.apache.axiom.om.OMElement; |
| import org.apache.axis2.jaxws.message.factory.BlockFactory; |
| |
| import javax.xml.namespace.QName; |
| import javax.xml.stream.XMLStreamException; |
| import javax.xml.stream.XMLStreamReader; |
| import javax.xml.stream.XMLStreamWriter; |
| import javax.xml.ws.WebServiceException; |
| |
| /** |
| * 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. |
| * <p/> |
| * The block can be exposed as: * BusinessObject * StAX object |
| * <p/> |
| * 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. |
| * <p/> |
| * 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 extends OMDataSourceExt { |
| |
| /** |
| * 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 WebServiceException |
| */ |
| public Object getBusinessObject(boolean consume) throws XMLStreamException, WebServiceException; |
| |
| /** |
| * 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, WebServiceException; |
| |
| /** |
| * 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 WebServiceException |
| */ |
| public OMElement getOMElement() throws XMLStreamException, WebServiceException; |
| |
| /** |
| * Write out the Block |
| * |
| * @param writer XMLStreamWriter |
| * @param consume true if this is the last request on the block. |
| * @throws XMLStreamException |
| * @trhows WebServiceException |
| */ |
| public void outputTo(XMLStreamWriter writer, boolean consume) |
| throws XMLStreamException, WebServiceException; |
| |
| /** |
| * 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. |
| * |
| * @return String containing trace information |
| * @boolean indent String containing indent characters |
| */ |
| 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. |
| * |
| * @return QName of the block |
| * @throw WebServiceException |
| * @see isQNameAvailable |
| */ |
| public QName getQName() throws WebServiceException; |
| |
| /** |
| * Get BlockFactory |
| * |
| * @return BlockFactory that created the Block |
| */ |
| public BlockFactory getBlockFactory(); |
| |
| /** |
| * Get the Message associated with this block |
| * |
| * @return Message |
| */ |
| public Message getParent(); |
| |
| /** |
| * Set the Message associated with this block (This method is intended to be called by the |
| * Message Implementation only) |
| * |
| * @param parent |
| */ |
| public void setParent(Message parent); |
| |
| /** |
| * @return true if data is always an element; false if possibly mixed content or multiple |
| * elements |
| */ |
| public boolean isElementData(); |
| } |