All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.apache.camel.Message Maven / Gradle / Ivy

Go to download

The Core Camel Java DSL based router

There is a newer version: 4.6.0
Show newest version
/**
 * 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.camel;

import java.util.Map;
import java.util.Set;
import java.util.function.Supplier;
import javax.activation.DataHandler;

import org.apache.camel.spi.HeadersMapFactory;

/**
 * Implements the Message pattern and
 * represents an inbound or outbound message as part of an {@link Exchange}.
 * 

 * See {@link org.apache.camel.impl.DefaultMessage DefaultMessage} for how headers
 * is represented in Camel using a {@link org.apache.camel.util.CaseInsensitiveMap CaseInsensitiveMap}.
 * The implementation of the map can be configured by the {@link HeadersMapFactory} which can be set
 * on the {@link CamelContext}. The default implementation uses the {@link org.apache.camel.util.CaseInsensitiveMap CaseInsensitiveMap}.
 *
 * @version 
 */
public interface Message {

    /**
     * Returns the id of the message
     *
     * @return the message id
     */
    String getMessageId();

    /**
     * Sets the id of the message
     *
     * @param messageId id of the message
     */
    void setMessageId(String messageId);

    /**
     * Returns the exchange this message is related to
     *
     * @return the exchange
     */
    Exchange getExchange();

    /**
     * Returns true if this message represents a fault
     *
     * @return true if this is a fault message, false for regular messages.
     */
    boolean isFault();

    /**
     * Sets the fault flag on this message
     *
     * @param fault the fault flag
     */
    void setFault(boolean fault);

    /**
     * Accesses a specific header
     *
     * @param name  name of header
     * @return the value of the given header or null if there is no
     *         header for the given name
     */
    Object getHeader(String name);

    /**
     * Accesses a specific header
     *
     * @param name  name of header
     * @param defaultValue the default value to return if header was absent
     * @return the value of the given header or defaultValue if there is no
     *         header for the given name
     */
    Object getHeader(String name, Object defaultValue);

    /**
     * Accesses a specific header
     *
     * @param name  name of header
     * @param defaultValueSupplier the default value supplier used to generate the value to return if header was absent
     * @return the value of the given header or he value generated by the defaultValueSupplier if there is no
     *         header for the given name
     */
    Object getHeader(String name, Supplier defaultValueSupplier);

    /**
     * Returns a header associated with this message by name and specifying the
     * type required
     *
     * @param name the name of the header
     * @param type the type of the header
     * @return the value of the given header or null if there is no header for
     *         the given name
     * @throws TypeConversionException is thrown if error during type conversion
     */
     T getHeader(String name, Class type);

    /**
     * Returns a header associated with this message by name and specifying the
     * type required
     *
     * @param name the name of the header
     * @param defaultValue the default value to return if header was absent
     * @param type the type of the header
     * @return the value of the given header or defaultValue if there is no header for
     *         the given name or null if it cannot be converted to the given type
     */
     T getHeader(String name, Object defaultValue, Class type);

    /**
     * Returns a header associated with this message by name and specifying the
     * type required
     *
     * @param name the name of the header
     * @param defaultValueSupplier the default value supplier used to generate the value to return if header was absent
     * @param type the type of the header
     * @return the value of the given header or he value generated by the defaultValueSupplier if there is no
     *         header for the given name or null if it cannot be converted to the given type
     */
     T getHeader(String name, Supplier defaultValueSupplier, Class type);

    /**
     * Sets a header on the message
     *
     * @param name of the header
     * @param value to associate with the name
     */
    void setHeader(String name, Object value);

    /**
     * Removes the named header from this message
     *
     * @param name name of the header
     * @return the old value of the header
     */
    Object removeHeader(String name);

    /**
     * Removes the headers from this message
     *
     * @param pattern pattern of names
     * @return boolean whether any headers matched
     */
    boolean removeHeaders(String pattern);
    
    /**
     * Removes the headers from this message that match the given pattern, 
     * except for the ones matching one or more excludePatterns
     * 
     * @param pattern pattern of names that should be removed
     * @param excludePatterns one or more pattern of header names that should be excluded (= preserved)
     * @return boolean whether any headers matched
     */ 
    boolean removeHeaders(String pattern, String... excludePatterns);

    /**
     * Returns all of the headers associated with the message.
     * 

     * See {@link org.apache.camel.impl.DefaultMessage DefaultMessage} for how headers
     * is represented in Camel using a {@link org.apache.camel.util.CaseInsensitiveMap CaseInsensitiveMap}.
     * The implementation of the map can be configured by the {@link HeadersMapFactory} which can be set
     * on the {@link CamelContext}. The default implementation uses the {@link org.apache.camel.util.CaseInsensitiveMap CaseInsensitiveMap}.
     * 

     * Important: If you want to walk the returned {@link Map} and fetch all the keys and values, you should use
     * the {@link java.util.Map#entrySet()} method, which ensure you get the keys in the original case.
     *
     * @return all the headers in a Map
     */
    Map getHeaders();

    /**
     * Set all the headers associated with this message
     * 

     * Important: If you want to copy headers from another {@link Message} to this {@link Message}, then
     * use getHeaders().putAll(other) to copy the headers, where other is the other headers.
     *
     * @param headers headers to set
     */
    void setHeaders(Map headers);

    /**
     * Returns whether has any headers has been set.
     *
     * @return true if any headers has been set
     */
    boolean hasHeaders();

    /**
     * Returns the body of the message as a POJO
     * 

     * The body can be null if no body is set.
     * 

     * Notice if the message body is stream based then calling this method multiple times may lead to the stream not being able to be re-read again.
     * You can enable stream caching and call the {@link StreamCache#reset()} method to reset the stream to be able to re-read again (if possible).
     * See more details about stream caching.
     *
     * @return the body, can be null
     */
    Object getBody();

    /**
     * Returns the body of the message as a POJO
     * 

     * Notice if the message body is stream based then calling this method multiple times may lead to the stream not being able to be re-read again.
     * See more details about stream caching.
     *
     * @return the body, is never null
     * @throws InvalidPayloadException Is thrown if the body being null or wrong class type
     */
    Object getMandatoryBody() throws InvalidPayloadException;

    /**
     * Returns the body as the specified type
     * 

     * Notice if the message body is stream based then calling this method multiple times may lead to the stream not being able to be re-read again.
     * You can enable stream caching and call the {@link StreamCache#reset()} method to reset the stream to be able to re-read again (if possible).
     * See more details about stream caching.
     *
     * @param type the type that the body
     * @return the body of the message as the specified type, or null if no body exists
     * @throws TypeConversionException is thrown if error during type conversion
     */
     T getBody(Class type);

    /**
     * Returns the mandatory body as the specified type
     * 

     * Notice if the message body is stream based then calling this method multiple times may lead to the stream not being able to be re-read again.
     * You can enable stream caching and call the {@link StreamCache#reset()} method to reset the stream to be able to re-read again (if possible).
     * See more details about stream caching.
     *
     * @param type the type that the body
     * @return the body of the message as the specified type, is never null.
     * @throws InvalidPayloadException Is thrown if the body being null or wrong class type
     */
     T getMandatoryBody(Class type) throws InvalidPayloadException;

    /**
     * Sets the body of the message
     *
     * @param body the body
     */
    void setBody(Object body);

    /**
     * Sets the body of the message as a specific type
     *
     * @param body the body
     * @param type the type of the body
     */
     void setBody(Object body, Class type);

    /**
     * Creates a copy of this message so that it can be used and possibly
     * modified further in another exchange
     *
     * @return a new message instance copied from this message
     */
    Message copy();

    /**
     * Copies the contents of the other message into this message
     * 

     * If you need to do a copy and then set a new body,
     * then use {@link #copyFromWithNewBody(Message, Object)} method instead.
     *
     * @param message the other message
     * @see #copyFromWithNewBody(Message, Object)
     */
    void copyFrom(Message message);
    
    /**
     * Copies the contents (except the body) of the other message into this message and uses the provided new body instead
     *
     * @param message the other message
     * @param newBody the new body to use
     */
    void copyFromWithNewBody(Message message, Object newBody);

    /**
     * Copies the attachments of the other message into this message
     *
     * @param message the other message
     */
    void copyAttachments(Message message);

    /**
     * Returns the attachment specified by the id
     *
     * @param id the id under which the attachment is stored
     * @return the data handler for this attachment or null
     */
    DataHandler getAttachment(String id);

    /**
     * Returns the attachment specified by the id
     *
     * @param id the id under which the attachment is stored
     * @return the attachment or null
     */
    Attachment getAttachmentObject(String id);

    /**
     * Returns a set of attachment names of the message
     *
     * @return a set of attachment names
     */
    Set getAttachmentNames();

    /**
     * Removes the attachment specified by the id
     *
     * @param id   the id of the attachment to remove
     */
    void removeAttachment(String id);

    /**
     * Adds an attachment to the message using the id
     *
     * @param id        the id to store the attachment under
     * @param content   the data handler for the attachment
     */
    void addAttachment(String id, DataHandler content);

    /**
     * Adds an attachment to the message using the id
     *
     * @param id        the id to store the attachment under
     * @param content   the attachment
     */
    void addAttachmentObject(String id, Attachment content);

    /**
     * Returns all attachments of the message
     *
     * @return the attachments in a map or null
     */
    Map getAttachments();

    /**
     * Returns all attachments of the message
     *
     * @return the attachments in a map or null
     */
    Map getAttachmentObjects();

    /**
     * Set all the attachments associated with this message
     *
     * @param attachments the attachments
     */
    void setAttachments(Map attachments);

    /**
     * Set all the attachments associated with this message
     *
     * @param attachments the attachments
     */
    void setAttachmentObjects(Map attachments);

    /**
     * Returns whether this message has attachments.
     *
     * @return true if this message has any attachments.
     */
    boolean hasAttachments();

    /**
     * Returns the unique ID for a message exchange if this message is capable
     * of creating one or null if not
     *
     * @return the created exchange id, or null if not capable of creating
     * @deprecated will be removed in Camel 3.0. It is discouraged for messages to create exchange ids
     */
    @Deprecated
    String createExchangeId();
}
 















© 2015 - 2024 Weber Informatics LLC | Privacy Policy