/*******************************************************************************
* Copyright (c) 2006-2010 eBay Inc. All Rights Reserved.
* 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
*******************************************************************************/
package org.ebayopensource.turmeric.runtime.common.pipeline;
import java.io.OutputStream;
import java.util.Map;
import javax.activation.DataHandler;
import javax.xml.stream.XMLStreamWriter;
import org.ebayopensource.turmeric.runtime.common.exceptions.ServiceException;
import org.ebayopensource.turmeric.runtime.common.types.G11nOptions;
/**
* Defines Message interface extensions for outbound message cases.
*
* @author ichernyshev, wdeng
*/
public interface OutboundMessage extends Message {
/**
* Called by the service provider framework to provide an outbound response containing errors.
* @param error An object to be reported as error response.
* @throws ServiceException Exception thrown when failed.
*/
public void setErrorResponse(Object error) throws ServiceException;
/**
* Called by the transport to serialize the message into the output stream.
* @param out the OutputStream into which to serialize the message's data
* @throws ServiceException Exception thrown when failed.
*/
public void serialize(OutputStream out) throws ServiceException;
/**
* Called by the transport to serialize only the body into the output stream.
* @param out the OutputStream into which to serialize the message's data
* @throws ServiceException Exception thrown when failed.
*/
public void serializeBody(OutputStream out) throws ServiceException;
/**
* To serialize the message header into the output stream.
* @param out the XMLStreamWriter into which to serialize the message's data
* @throws ServiceException Exception thrown when failed.
*/
public void serializeHeader(XMLStreamWriter out) throws ServiceException;
/**
* Called by the transport to build the finalized list of headers that should be sent over the communication
* channel. This should include SOA framework headers, user headers, and any adjunct e.g. attachment or message
* protocol related headers. Information is assembled by the message implementation using its own state information
* and information in the associate message context.
* @return the map of transport headers
* @throws ServiceException Exception thrown when failed.
*/
public Map<String, String> buildOutputHeaders() throws ServiceException;
/**
* Called by attachment marshallers to add a data interface for an attachment.
* @param dh the data handler associated with this attachment
* @param id the attachment identifier
*/
public void addDataHandler(DataHandler dh, String id);
/**
* Set the globalization options into the outbound message.
* @param options the globalization options
*/
public void setG11nOptions(G11nOptions options);
/**
* Sets a filter stream on the message which will intercept the message's base
* output stream. This is used for payload logging.
*
* @param maxBytes the maximum number of bytes to be filtered (i.e. logged).
* @throws ServiceException Exception thrown when failed.
*/
public void recordPayload(int maxBytes) throws ServiceException;
/**
* @return A copy of the recorded data.
* @throws ServiceException Exception thrown when failed.
*/
public byte[] getRecordedData() throws ServiceException;
/**
* Returns true if the message will be sent REST style, e.g. HTTP GET method will be used.
* (Only relevant to client-side outbound messages; returns false otherwise)
* @return true if the message will be sent REST style.
*/
public boolean isREST();
/**
* Returns the configured maximum length into which to code URL information for an HTTP GET. The framework
* will throw an exception for requests that exceed this length. Transports will implement some default
* if this value is not available.
* @return the maximum URL encoding length
*/
public int getMaxURLLengthForREST();
/**
* Indicate a fatal error on the response such that it cannot be sent back to the
* receiver, for example, a fatal error during custom error mapping, or inability to
* finalize the outbound message in some other way (setting headers, etc.) The transport
* should check for this condition.
* @param reason The general reason when fatal error is reported.
*/
public void setUnserializable(String reason);
/**
* Returns whether <code>setUnserializable()</code> has been set on this message.
* @return whether the message is unserializable
*/
public boolean isUnserializable();
/**
* Returns the string that was passed during <code>setUnserializable()</code> call, if any.
* @return the unserializable reason string
*/
public String getUnserializableReason();
/**
* Add message header as an java object.
* @param headerJavaObject A JavaObjectNode to be added as a message header.
* @throws ServiceException Exception thrown when failed.
*/
public void addMessageHeaderAsJavaObject(Object headerJavaObject) throws ServiceException;
/**
* Returns the value that is used to signal error flow at transport level.
* @return the transport error response indication code
* @throws ServiceException Exception thrown when failed.
*/
public int getTransportErrorResponseIndicationCode() throws ServiceException;
}