001/*
002 * Trident - A Multithreaded Server Alternative
003 * Copyright 2014 The TridentSDK Team
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * 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 net.tridentsdk.meta.component;
018
019import javax.annotation.concurrent.ThreadSafe;
020
021/**
022 * Represents an object which carries metadata
023 *
024 * @author The TridentSDK Team
025 * @since 0.4-alpha
026 */
027@ThreadSafe
028public interface MetaOwner<T> {
029    /**
030     * Obtains the meta tag from the class type
031     *
032     * @param cls the class type of the meta value
033     * @param <M> the meta type
034     * @return the meta value, or {@code null} if the meta is not owned
035     */
036    <M extends T> M obtainMeta(Class<M> cls);
037
038    /**
039     * Creates a new metadata value for the type specified if this block supports it, and it is not already
040     * created in the block
041     *
042     * @param cls the meta type
043     * @param <M> the meta
044     * @return the meta value, or {@code null} if it could not be made
045     */
046    <M extends T> M newMetaIfNull(Class<M> cls);
047
048    /**
049     * Gets all of the metadata values currently owned by this meta owner
050     *
051     * @return the currently owned collection of meta values
052     */
053    <M extends MetaOwner> MetaCollection<M> ownedMeta();
054
055    /**
056     * Applies the specified metas to the owner, replacing the previous value if present
057     *
058     * @param meta the metas to apply
059     * @param <M> the meta type
060     */
061    <M extends T> void applyMeta(M... meta);
062
063    /**
064     * Commits the changes from the meta value to the block
065     *
066     * @param meta    the metadata
067     * @param replace {@code true} to apply meta anyways if the data mapping already exists
068     * @param <M>     the meta type
069     * @return {@code true} if the <em>all</em> of the meta changes took effect
070     */
071    <M extends T> boolean applyMeta(boolean replace, M... meta);
072
073    /**
074     * Removes all meta values and sets the block meta to {@code (byte) 0}
075     */
076    void clearMeta();
077}