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.service;
018
019import javax.annotation.concurrent.ThreadSafe;
020
021/**
022 * Represents an object which holds tags called permissions
023 *
024 * <p>The granting of permissions does not necessarily reflect an immediate action, rather it is a condition variable
025 * which is invoked by the handler for that particular permission.</p>
026 *
027 * @author The TridentSDK Team
028 * @since 0.3-alpha-DP
029 */
030@ThreadSafe
031public interface PermissionOwner {
032    /**
033     * Offers the permission holder a permission which they can hold
034     *
035     * <p>This has no effect if the holder already has the given permission</p>
036     *
037     * @param perm the new permission the holder should hold
038     */
039    void grantPermission(String perm);
040
041    /**
042     * Removes the permission tag from the holder such that the next invocation of {@link #ownsPermission(String)}
043     * returns {@code false}
044     *
045     * @param perm the permission to remove
046     */
047    void revokePermission(String perm);
048
049    /**
050     * Observes the holder to see if it holds the specified permission
051     *
052     * @param perm the permission to check if held
053     * @return {@code true} if the permission is held, {@code false} if it is not
054     */
055    boolean ownsPermission(String perm);
056
057    /**
058     * Checks if the permission holder has operator status
059     *
060     * @return {@code true} to indicate that the holder is an operator
061     */
062    boolean opped();
063}