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.marshaller;
020:
021: import org.apache.axis2.jaxws.description.OperationDescription;
022: import org.apache.axis2.jaxws.message.Message;
023: import org.apache.axis2.jaxws.message.Protocol;
024:
025: import javax.xml.ws.WebServiceException;
026:
027: /**
028: * This class marshals and unmarshals method invocations.
029: * <p/>
030: * Here is the high-level view of marshalling: SIGNATURE_ARGS ---> Type Enabled Object ----->
031: * Element Enabled Object ---> MESSAGE (XML)
032: * <p/>
033: * The Signature objects are the objects from the SEI method signature. They may be values or
034: * holders of values. The values are "type enabled objects" (i.e. String), which means that they
035: * cannot be marshalled or unmarshalled.
036: *
037: * @see org.apache.axis2.jaxws.util.XMLRootElementUtils for details on Type Enabled and Element
038: * Enabled objects.
039: * <p/>
040: * The values are enhanced (if necessary) into Element Enabled Objects. These can be
041: * marshalled or unmarshalled using JAXB.
042: * @see org.apache.axis2.jaxws.marshaller.impl.alt.PDElement
043: * <p/>
044: * The element enabled objects are put onto the message.
045: * <p/>
046: * The high-level view of unmarshalling is the reverse. SIGNATURE_ARGS <---- Type Enabled
047: * Object <----- Element Enabled Object <---- MESSAGE (XML)
048: * <p/>
049: * See the specific MethodMarshaller implementations to see how doc/lit wrapped, doc/lit bare
050: * and rpc/lit affect the process of going from SIGNATURE_ARGS to the element enabled objects.
051: * <p/>
052: * If there are any problems, a WebServiceException is thrown. (Each of the methods is
053: * guranteed to catch any unchecked exception and wrap it in a WebServiceException).
054: */
055: public interface MethodMarshaller {
056:
057: /**
058: * This method converts SIGNATURE_ARGS into a Message. It is used on the client
059: *
060: * @param signatureArgs
061: * @return Message
062: */
063: public Message marshalRequest(Object[] signatureArgs,
064: OperationDescription opDesc) throws WebServiceException;
065:
066: /**
067: * This method converts the SIGNATURE_ARGS and RETURN object into a Message. It is used on the
068: * server
069: *
070: * @param returnObject
071: * @param signatureArgs
072: * @param OperationDesc
073: * @param Protocol for response
074: * @return Message
075: */
076: public Message marshalResponse(Object returnObject,
077: Object[] signatureArgs, OperationDescription opDesc,
078: Protocol protocol) throws WebServiceException;
079:
080: /**
081: * This method converts the Message into a SIGNATURE_ARGS It is used on the server
082: *
083: * @param message
084: * @return signature args
085: */
086: public Object[] demarshalRequest(Message message,
087: OperationDescription opDesc) throws WebServiceException;
088:
089: /**
090: * This method gets the objects from the Message and sets them onto the SIGNATURE_ARGS It also
091: * returns the RETURN object. Called on client
092: *
093: * @param message
094: * @param signatureAgs (same array of args that were used for marshalRequest. The out/inout
095: * holders are populated with new values)
096: * @param OperationDesc
097: * @return returnObject
098: */
099: public Object demarshalResponse(Message message,
100: Object[] signatureArgs, OperationDescription opDesc)
101: throws WebServiceException;
102:
103: /**
104: * This method converts a Message (containing a fault) into a JAX-WS Service or
105: * WebServiceException. Used on the client.
106: *
107: * @param message
108: * @param Message
109: * @return Throwable
110: */
111: public Throwable demarshalFaultResponse(Message message,
112: OperationDescription opDesc) throws WebServiceException;
113:
114: /**
115: * This method creates a Message from a Throwable input parameter. Used on the server.
116: *
117: * @param Throwable
118: * @param OperationDesc
119: * @param Protocol for response
120: * @return
121: */
122: public Message marshalFaultResponse(Throwable throwable,
123: OperationDescription opDesc, Protocol protocol)
124: throws WebServiceException;
125:
126: }
|