001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2010–2011 ApexIdentity Inc.
015 * Portions Copyright 2011-2014 ForgeRock AS.
016 */
017
018package org.forgerock.openig.header;
019
020import org.forgerock.openig.http.Message;
021import org.forgerock.openig.util.Indexed;
022
023/**
024 * An HTTP message header.
025 */
026public interface Header extends Indexed<String> {
027
028    /**
029     * Returns the name of the header, as it would canonically appear within an HTTP message.
030     *
031     * @return The name of the header, as it would canonically appear within an HTTP message.
032     */
033    @Override
034    String getKey();
035
036    /**
037     * Populates the content of the header from the specified message. If the message does not contain the appropriate
038     * header, calling this message has no effect (will not change the values of the header).
039     *
040     * @param message
041     *            The message to get the content of the header from.
042     */
043    void fromMessage(Message<?> message);
044
045    /**
046     * Populates the content of the header from the specified string value.
047     *
048     * @param string
049     *            The string to populate the content of the header from.
050     */
051    void fromString(String string);
052
053    /**
054     * Sets the header in the specified message. If the header is empty, calling this method has no effect (will not
055     * erase existing instances of the header in the message).
056     *
057     * @param message
058     *            The message to which add the current header.
059     */
060    void toMessage(Message<?> message);
061
062    /**
063     * Returns the header as a single string value. If the header is empty, this method will return {@code null}.
064     *
065     * @return The header as a single string value or {@code null} if empty.
066     */
067    String toString();
068}