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 Sun Microsystems, Inc.
015 * Portions copyright 2013 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.server.core;
019
020import java.util.Set;
021
022/**
023 * Interface declares common functionality for objects, which can store
024 * {@link Attachment}s.
025 */
026public interface AttachmentHolder {
027    /**
028     * Retrieves the attachment with the specified name.
029     *
030     * @param name
031     *            The name for the attachment to retrieve. It will be treated in
032     *            a case-sensitive manner.
033     * @return The requested attachment object, or {@code null} if it does not
034     *         exist.
035     */
036    Object getAttachment(String name);
037
038    /**
039     * Retrieves the set of attachment names defined for this holder, as a
040     * mapping between the attachment name and the associated object.
041     *
042     * @return The set of attachments defined for this operation.
043     */
044    Set<String> getAttachmentNames();
045
046    /**
047     * Removes the attachment with the specified name.
048     *
049     * @param name
050     *            The name for the attachment to remove. It will be treated in a
051     *            case-sensitive manner.
052     * @return The attachment that was removed, or {@code null} if it does not
053     *         exist.
054     */
055    Object removeAttachment(String name);
056
057    /**
058     * Sets the value of the specified attachment. If an attachment already
059     * exists with the same name, it will be replaced. Otherwise, a new
060     * attachment will be added.
061     *
062     * @param name
063     *            The name to use for the attachment.
064     * @param value
065     *            The value to use for the attachment.
066     * @return The former value held by the attachment with the given name, or
067     *         {@code null} if there was previously no such attachment.
068     */
069    Object setAttachment(String name, Object value);
070}