001/**
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.camel.spi;
018
019import java.util.Map;
020
021import org.apache.camel.Message;
022
023/**
024 * Factory to create the {@link Map} implementation to use for storing headers on {@link Message}.
025 *
026 * @see org.apache.camel.impl.DefaultHeadersMapFactory
027 */
028public interface HeadersMapFactory {
029
030    /**
031     * Creates a new empty {@link Map}
032     *
033     * @return new empty map
034     */
035    Map<String, Object> newMap();
036
037    /**
038     * Creates a new {@link Map} and copies over all the content from the existing map.
039     * <p/>
040     * The copy of the content should use defensive copy, so the returned map
041     * can add/remove/change the content without affecting the existing map.
042     *
043     * @param map  existing map to copy over (must use defensive copy)
044     * @return new map with the content from the existing map
045     */
046    Map<String, Object> newMap(Map<String, Object> map);
047
048    /**
049     * Whether the given {@link Map} implementation is created by this factory?
050     *
051     * @return <tt>true</tt> if created from this factory, <tt>false</tt> if not
052     */
053    boolean isInstanceOf(Map<String, Object> map);
054
055    /**
056     * Whether the created {@link Map} are case insensitive or not.
057     * <p/>
058     * Important: When using case sensitive (this method return false).
059     * Then the map is case sensitive which means headers such as <tt>content-type</tt> and <tt>Content-Type</tt> are
060     * two different keys which can be a problem for some protocols such as HTTP based, which rely on case insensitive headers.
061     * However case sensitive implementations can yield faster performance. Therefore use case sensitive implementation with care.
062     */
063    boolean isCaseInsensitive();
064
065}
066