bundles/org.eclipse.osgi/osgi/src/org/osgi/service/condpermadmin/ConditionalPermissionAdmin.java - equinox/rt.equinox.framework - Git at Google

 /*
  * Copyright (c) OSGi Alliance (2005, 2009). 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.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
  * @version $Revision: 6782 $
  */
 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</code> 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</code> 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</code>.
 	 * @deprecated Since 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</code>, 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</code>.
 	 * @param conditions The conditions that need to be satisfied to enable the
 	 *        specified permissions. This argument can be <code>null</code> 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</code> 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</code>.
 	 * @deprecated Since 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 Since 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</code> if no Conditional Permission Info with the
 	 *         specified name exists in the Conditional Permission Table.
 	 * @deprecated Since 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</code> because the state is UNINSTALLED</li>
 	 * <li>All other methods return a <code>null</code></li>
 	 * </ul>
 	 * @param signers The signers for which to return an Access Control Context.
 	 * @return An <code>AccessControlContext</code> 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</code> method on <code>ConditionalPermissionInfo</code>
 	 * objects created with this method must throw
 	 * UnsupportedOperationException.
 	 *
 	 * @param name The name of the created
 	 *        <code>ConditionalPermissionInfo</code> or <code>null</code> to
 	 *        have a unique name generated when the returned
 	 *        <code>ConditionalPermissionInfo</code> 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</code> 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</code> 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</code> 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</code> from the specified
 	 * encoded <code>ConditionalPermissionInfo</code> string suitable for
 	 * insertion into a {@link ConditionalPermissionUpdate}. The
 	 * <code>delete</code> method on <code>ConditionalPermissionInfo</code>
 	 * objects created with this method must throw
 	 * UnsupportedOperationException.
 	 *
 	 * @param encodedConditionalPermissionInfo The encoded
 	 *        <code>ConditionalPermissionInfo</code>. White space in the encoded
 	 *        <code>ConditionalPermissionInfo</code> is ignored. The access
 	 *        decision value in the encoded
 	 *        <code>ConditionalPermissionInfo</code> must be evaluated case
 	 *        insensitively. If the encoded
 	 *        <code>ConditionalPermissionInfo</code> does not contain the
 	 *        optional name, <code>null</code> must be used for the name and a
 	 *        unique name will be generated when the returned
 	 *        <code>ConditionalPermissionInfo</code> is committed in an update
 	 *        to the Conditional Permission Table.
 	 * @return A <code>ConditionalPermissionInfo</code> object suitable for
 	 *         insertion into a {@link ConditionalPermissionUpdate}.
 	 * @throws IllegalArgumentException If the specified
 	 *         <code>encodedConditionalPermissionInfo</code> is not properly
 	 *         formatted.
 	 * @see ConditionalPermissionInfo#getEncoded
 	 * @since 1.1
 	 */
 	ConditionalPermissionInfo newConditionalPermissionInfo(
 			String encodedConditionalPermissionInfo);
 }
	/*
	* Copyright (c) OSGi Alliance (2005, 2009). 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.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
	* @version $Revision: 6782 $
	*/
	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</code> 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</code> 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</code>.
	* @deprecated Since 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</code>, 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</code>.
	* @param conditions The conditions that need to be satisfied to enable the
	* specified permissions. This argument can be <code>null</code> 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</code> 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</code>.
	* @deprecated Since 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 Since 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</code> if no Conditional Permission Info with the
	* specified name exists in the Conditional Permission Table.
	* @deprecated Since 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</code> because the state is UNINSTALLED</li>
	* <li>All other methods return a <code>null</code></li>
	* </ul>
	* @param signers The signers for which to return an Access Control Context.
	* @return An <code>AccessControlContext</code> 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</code> method on <code>ConditionalPermissionInfo</code>
	* objects created with this method must throw
	* UnsupportedOperationException.
	*
	* @param name The name of the created
	* <code>ConditionalPermissionInfo</code> or <code>null</code> to
	* have a unique name generated when the returned
	* <code>ConditionalPermissionInfo</code> 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</code> 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</code> 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</code> 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</code> from the specified
	* encoded <code>ConditionalPermissionInfo</code> string suitable for
	* insertion into a {@link ConditionalPermissionUpdate}. The
	* <code>delete</code> method on <code>ConditionalPermissionInfo</code>
	* objects created with this method must throw
	* UnsupportedOperationException.
	*
	* @param encodedConditionalPermissionInfo The encoded
	* <code>ConditionalPermissionInfo</code>. White space in the encoded
	* <code>ConditionalPermissionInfo</code> is ignored. The access
	* decision value in the encoded
	* <code>ConditionalPermissionInfo</code> must be evaluated case
	* insensitively. If the encoded
	* <code>ConditionalPermissionInfo</code> does not contain the
	* optional name, <code>null</code> must be used for the name and a
	* unique name will be generated when the returned
	* <code>ConditionalPermissionInfo</code> is committed in an update
	* to the Conditional Permission Table.
	* @return A <code>ConditionalPermissionInfo</code> object suitable for
	* insertion into a {@link ConditionalPermissionUpdate}.
	* @throws IllegalArgumentException If the specified
	* <code>encodedConditionalPermissionInfo</code> is not properly
	* formatted.
	* @see ConditionalPermissionInfo#getEncoded
	* @since 1.1
	*/
	ConditionalPermissionInfo newConditionalPermissionInfo(
	String encodedConditionalPermissionInfo);
	}