| /* |
| * Copyright (c) OSGi Alliance (2005, 2014). All Rights Reserved. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package org.osgi.service.condpermadmin; |
| |
| import java.security.AccessControlContext; |
| import java.util.Enumeration; |
| import org.osgi.annotation.versioning.ProviderType; |
| import org.osgi.service.permissionadmin.PermissionInfo; |
| |
| /** |
| * Framework service to administer Conditional Permissions. Conditional |
| * Permissions can be added to, retrieved from, and removed from the framework. |
| * Conditional Permissions are conceptually managed in an ordered table called |
| * the Conditional Permission Table. |
| * |
| * @ThreadSafe |
| * @author $Id$ |
| */ |
| @ProviderType |
| public interface ConditionalPermissionAdmin { |
| /** |
| * Create a new Conditional Permission Info in the Conditional Permission |
| * Table. |
| * <p> |
| * The Conditional Permission Info will be given a unique, never reused |
| * name. This entry will be added at the beginning of the Conditional |
| * Permission Table with an access decision of |
| * {@link ConditionalPermissionInfo#ALLOW ALLOW}. |
| * <p> |
| * Since this method changes the Conditional Permission Table any |
| * {@link ConditionalPermissionUpdate}s that were created prior to calling |
| * this method can no longer be committed. |
| * |
| * @param conditions The conditions that need to be satisfied to enable the |
| * specified permissions. This argument can be {@code null} or an |
| * empty array indicating the specified permissions are not guarded |
| * by any conditions. |
| * @param permissions The permissions that are enabled when the specified |
| * conditions, if any, are satisfied. This argument must not be |
| * {@code null} and must specify at least one permission. |
| * @return The ConditionalPermissionInfo for the specified Conditions and |
| * Permissions. |
| * @throws IllegalArgumentException If no permissions are specified. |
| * @throws SecurityException If the caller does not have |
| * {@code AllPermission}. |
| * @deprecated As of 1.1. Use {@link #newConditionalPermissionUpdate()} |
| * instead. |
| */ |
| ConditionalPermissionInfo addConditionalPermissionInfo(ConditionInfo[] conditions, PermissionInfo[] permissions); |
| |
| /** |
| * Set or create a Conditional Permission Info with a specified name in the |
| * Conditional Permission Table. |
| * <p> |
| * If the specified name is {@code null}, a new Conditional Permission Info |
| * must be created and will be given a unique, never reused name. If there |
| * is currently no Conditional Permission Info with the specified name, a |
| * new Conditional Permission Info must be created with the specified name. |
| * Otherwise, the Conditional Permission Info with the specified name must |
| * be updated with the specified Conditions and Permissions. If a new entry |
| * was created in the Conditional Permission Table it will be added at the |
| * beginning of the table with an access decision of |
| * {@link ConditionalPermissionInfo#ALLOW ALLOW}. |
| * <p> |
| * Since this method changes the underlying permission table any |
| * {@link ConditionalPermissionUpdate}s that were created prior to calling |
| * this method can no longer be committed. |
| * |
| * @param name The name of the Conditional Permission Info, or {@code null}. |
| * @param conditions The conditions that need to be satisfied to enable the |
| * specified permissions. This argument can be {@code null} or an |
| * empty array indicating the specified permissions are not guarded |
| * by any conditions. |
| * @param permissions The permissions that are enabled when the specified |
| * conditions, if any, are satisfied. This argument must not be |
| * {@code null} and must specify at least one permission. |
| * @return The ConditionalPermissionInfo for the specified name, Conditions |
| * and Permissions. |
| * @throws IllegalArgumentException If no permissions are specified. |
| * @throws SecurityException If the caller does not have |
| * {@code AllPermission}. |
| * @deprecated As of 1.1. Use {@link #newConditionalPermissionUpdate()} |
| * instead. |
| */ |
| ConditionalPermissionInfo setConditionalPermissionInfo(String name, ConditionInfo[] conditions, PermissionInfo[] permissions); |
| |
| /** |
| * Returns the Conditional Permission Infos from the Conditional Permission |
| * Table. |
| * <p> |
| * The returned Enumeration will return elements in the order they are kept |
| * in the Conditional Permission Table. |
| * <p> |
| * The Enumeration returned is based on a copy of the Conditional Permission |
| * Table and therefore will not throw exceptions if the Conditional |
| * Permission Table is changed during the course of reading elements from |
| * the Enumeration. |
| * |
| * @return An enumeration of the Conditional Permission Infos that are |
| * currently in the Conditional Permission Table. |
| * @deprecated As of 1.1. Use {@link #newConditionalPermissionUpdate()} |
| * instead. |
| */ |
| Enumeration<ConditionalPermissionInfo> getConditionalPermissionInfos(); |
| |
| /** |
| * Return the Conditional Permission Info with the specified name. |
| * |
| * @param name The name of the Conditional Permission Info to be returned. |
| * @return The Conditional Permission Info with the specified name or |
| * {@code null} if no Conditional Permission Info with the specified |
| * name exists in the Conditional Permission Table. |
| * @deprecated As of 1.1. Use {@link #newConditionalPermissionUpdate()} |
| * instead. |
| */ |
| ConditionalPermissionInfo getConditionalPermissionInfo(String name); |
| |
| /** |
| * Returns the Access Control Context that corresponds to the specified |
| * signers. |
| * |
| * The returned Access Control Context must act as if its protection domain |
| * came from a bundle that has the following characteristics: |
| * <ul> |
| * <li>It is signed by all of the given signers</li> |
| * <li>It has a bundle id of -1</li> |
| * <li>Its location is the empty string</li> |
| * <li>Its state is UNINSTALLED</li> |
| * <li>It has no headers</li> |
| * <li>It has the empty version (0.0.0)</li> |
| * <li>Its last modified time=0</li> |
| * <li>Many methods will throw {@code IllegalStateException} because the |
| * state is UNINSTALLED</li> |
| * <li>All other methods return a {@code null}</li> |
| * </ul> |
| * |
| * @param signers The signers for which to return an Access Control Context. |
| * @return An {@code AccessControlContext} that has the Permissions |
| * associated with the signer. |
| */ |
| AccessControlContext getAccessControlContext(String[] signers); |
| |
| /** |
| * Creates a new update for the Conditional Permission Table. The update is |
| * a working copy of the current Conditional Permission Table. If the |
| * running Conditional Permission Table is modified before commit is called |
| * on the returned update, then the call to commit on the returned update |
| * will fail. That is, the commit method will return false and no change |
| * will be made to the running Conditional Permission Table. There is no |
| * requirement that commit is eventually called on the returned update. |
| * |
| * @return A new update for the Conditional Permission Table. |
| * @since 1.1 |
| */ |
| ConditionalPermissionUpdate newConditionalPermissionUpdate(); |
| |
| /** |
| * Creates a new ConditionalPermissionInfo with the specified fields |
| * suitable for insertion into a {@link ConditionalPermissionUpdate}. The |
| * {@code delete} method on {@code ConditionalPermissionInfo} objects |
| * created with this method must throw UnsupportedOperationException. |
| * |
| * @param name The name of the created {@code ConditionalPermissionInfo} or |
| * {@code null} to have a unique name generated when the returned |
| * {@code ConditionalPermissionInfo} is committed in an update to the |
| * Conditional Permission Table. |
| * @param conditions The conditions that need to be satisfied to enable the |
| * specified permissions. This argument can be {@code null} or an |
| * empty array indicating the specified permissions are not guarded |
| * by any conditions. |
| * @param permissions The permissions that are enabled when the specified |
| * conditions, if any, are satisfied. This argument must not be |
| * {@code null} and must specify at least one permission. |
| * @param access Access decision. Must be one of the following values: |
| * <ul> |
| * <li>{@link ConditionalPermissionInfo#ALLOW allow}</li> |
| * <li>{@link ConditionalPermissionInfo#DENY deny}</li> |
| * </ul> |
| * The specified access decision value must be evaluated case |
| * insensitively. |
| * @return A {@code ConditionalPermissionInfo} object suitable for insertion |
| * into a {@link ConditionalPermissionUpdate}. |
| * @throws IllegalArgumentException If no permissions are specified or if |
| * the specified access decision is not a valid value. |
| * @since 1.1 |
| */ |
| ConditionalPermissionInfo newConditionalPermissionInfo(String name, ConditionInfo[] conditions, PermissionInfo[] permissions, String access); |
| |
| /** |
| * Creates a new {@code ConditionalPermissionInfo} from the specified |
| * encoded {@code ConditionalPermissionInfo} string suitable for insertion |
| * into a {@link ConditionalPermissionUpdate}. The {@code delete} method on |
| * {@code ConditionalPermissionInfo} objects created with this method must |
| * throw UnsupportedOperationException. |
| * |
| * @param encodedConditionalPermissionInfo The encoded |
| * {@code ConditionalPermissionInfo}. White space in the encoded |
| * {@code ConditionalPermissionInfo} is ignored. The access decision |
| * value in the encoded {@code ConditionalPermissionInfo} must be |
| * evaluated case insensitively. If the encoded |
| * {@code ConditionalPermissionInfo} does not contain the optional |
| * name, {@code null} must be used for the name and a unique name |
| * will be generated when the returned |
| * {@code ConditionalPermissionInfo} is committed in an update to the |
| * Conditional Permission Table. |
| * @return A {@code ConditionalPermissionInfo} object suitable for insertion |
| * into a {@link ConditionalPermissionUpdate}. |
| * @throws IllegalArgumentException If the specified |
| * {@code encodedConditionalPermissionInfo} is not properly |
| * formatted. |
| * @see ConditionalPermissionInfo#getEncoded() |
| * @since 1.1 |
| */ |
| ConditionalPermissionInfo newConditionalPermissionInfo(String encodedConditionalPermissionInfo); |
| } |
