http://www.eclipse.org/platform: OSGi System Bundle %systemBundle (Eclipse Foundation) 
/*
 * Copyright (c) OSGi Alliance (2001, 2016). 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.permissionadmin;


Permission representation used by the Permission Admin service.


This class encapsulates three pieces of information: a Permission type
 (class name), which must be a subclass of java.security.Permission, and the name and actions
arguments passed to its constructor.

 In order for a permission represented by a PermissionInfo to be instantiated and considered during a permission check, its Permission class must be available from the system classpath or an exported package. This means that the instantiation of a permission represented by a PermissionInfo may be delayed until the package containing its Permission class has been exported by a bundle. 
Author:$Id: 7ca97aeef2f56fafd7aebe6e7e0e0cdad9968489 $
@Immutable
/**
 * Permission representation used by the Permission Admin service.
 * 
 * <p>
 * This class encapsulates three pieces of information: a Permission <i>type
 * </i> (class name), which must be a subclass of
 * {@code java.security.Permission}, and the <i>name</i> and <i>actions</i>
 * arguments passed to its constructor.
 * 
 * <p>
 * In order for a permission represented by a {@code PermissionInfo} to be
 * instantiated and considered during a permission check, its Permission class
 * must be available from the system classpath or an exported package. This
 * means that the instantiation of a permission represented by a
 * {@code PermissionInfo} may be delayed until the package containing its
 * Permission class has been exported by a bundle.
 * 
 * @Immutable
 * @author $Id: 7ca97aeef2f56fafd7aebe6e7e0e0cdad9968489 $
 */
public class PermissionInfo {
	private final String	type;
	private final String	name;
	private final String	actions;

	
Constructs a PermissionInfo from the specified type, name, and actions. 
Params:
  • type – The fully qualified class name of the permission represented by this PermissionInfo. The class must be a subclass of java.security.Permission and must define a 2-argument constructor that takes a name string and an actions
       string.
  • name – The permission name that will be passed as the first argument to the constructor of the Permission class identified by type.
  • actions – The permission actions that will be passed as the second argument to the constructor of the Permission class identified by type.
Throws:
/**
	 * Constructs a {@code PermissionInfo} from the specified type, name, and
	 * actions.
	 * 
	 * @param type The fully qualified class name of the permission represented
	 *        by this {@code PermissionInfo}. The class must be a subclass of
	 *        {@code java.security.Permission} and must define a 2-argument
	 *        constructor that takes a <i>name</i> string and an <i>actions</i>
	 *        string.
	 * 
	 * @param name The permission name that will be passed as the first argument
	 *        to the constructor of the {@code Permission} class identified by
	 *        {@code type}.
	 * 
	 * @param actions The permission actions that will be passed as the second
	 *        argument to the constructor of the {@code Permission} class
	 *        identified by {@code type}.
	 * 
	 * @throws NullPointerException If {@code type} is {@code null}.
	 * @throws IllegalArgumentException If {@code action} is not {@code null}
	 *         and {@code name} is {@code null}.
	 */
	public PermissionInfo(String type, String name, String actions) {
		this.type = type;
		this.name = name;
		this.actions = actions;
		if (type == null) {
			throw new NullPointerException("type is null");
		}
		if ((name == null) && (actions != null)) {
			throw new IllegalArgumentException("name missing");
		}
	}

	
Constructs a PermissionInfo object from the specified encoded PermissionInfo string. White space in the encoded PermissionInfo string is ignored. 
Params:
  • encodedPermission – The encoded PermissionInfo.
Throws:
See Also:
/**
	 * Constructs a {@code PermissionInfo} object from the specified encoded
	 * {@code PermissionInfo} string. White space in the encoded
	 * {@code PermissionInfo} string is ignored.
	 * 
	 * 
	 * @param encodedPermission The encoded {@code PermissionInfo}.
	 * @see #getEncoded()
	 * @throws IllegalArgumentException If the specified
	 *         {@code encodedPermission} is not properly formatted.
	 */
	public PermissionInfo(String encodedPermission) {
		if (encodedPermission == null) {
			throw new NullPointerException("missing encoded permission");
		}
		if (encodedPermission.length() == 0) {
			throw new IllegalArgumentException("empty encoded permission");
		}
		String parsedType = null;
		String parsedName = null;
		String parsedActions = null;
		try {
			char[] encoded = encodedPermission.toCharArray();
			int length = encoded.length;
			int pos = 0;

			/* skip whitespace */
			while (Character.isWhitespace(encoded[pos])) {
				pos++;
			}

			/* the first character must be '(' */
			if (encoded[pos] != '(') {
				throw new IllegalArgumentException("expecting open parenthesis");
			}
			pos++;

			/* skip whitespace */
			while (Character.isWhitespace(encoded[pos])) {
				pos++;
			}

			/* type is not quoted or encoded */
			int begin = pos;
			while (!Character.isWhitespace(encoded[pos]) && (encoded[pos] != ')')) {
				pos++;
			}
			if (pos == begin || encoded[begin] == '"') {
				throw new IllegalArgumentException("expecting type");
			}
			parsedType = new String(encoded, begin, pos - begin);

			/* skip whitespace */
			while (Character.isWhitespace(encoded[pos])) {
				pos++;
			}

			/* type may be followed by name which is quoted and encoded */
			if (encoded[pos] == '"') {
				pos++;
				begin = pos;
				while (encoded[pos] != '"') {
					if (encoded[pos] == '\\') {
						pos++;
					}
					pos++;
				}
				parsedName = unescapeString(encoded, begin, pos);
				pos++;

				if (Character.isWhitespace(encoded[pos])) {
					/* skip whitespace */
					while (Character.isWhitespace(encoded[pos])) {
						pos++;
					}

					/*
					 * name may be followed by actions which is quoted and
					 * encoded
					 */
					if (encoded[pos] == '"') {
						pos++;
						begin = pos;
						while (encoded[pos] != '"') {
							if (encoded[pos] == '\\') {
								pos++;
							}
							pos++;
						}
						parsedActions = unescapeString(encoded, begin, pos);
						pos++;

						/* skip whitespace */
						while (Character.isWhitespace(encoded[pos])) {
							pos++;
						}
					}
				}
			}

			/* the final character must be ')' */
			char c = encoded[pos];
			pos++;
			while ((pos < length) && Character.isWhitespace(encoded[pos])) {
				pos++;
			}
			if ((c != ')') || (pos != length)) {
				throw new IllegalArgumentException("expecting close parenthesis");
			}
		} catch (ArrayIndexOutOfBoundsException e) {
			throw new IllegalArgumentException("parsing terminated abruptly");
		}

		type = parsedType;
		name = parsedName;
		actions = parsedActions;
	}

	
Returns the string encoding of this PermissionInfo in a form suitable for restoring this PermissionInfo. 

The encoded format is:

(type)


or

(type "name")


or

(type "name" "actions")


where name and actions are strings that must be encoded for proper parsing. Specifically, the ",\, carriage return, and line feed characters must be escaped using \", \\, \r, and \n, respectively. 

The encoded string contains no leading or trailing whitespace characters.
A single space character is used between type and
"name" and between "name" and
"actions".

Returns:The string encoding of this PermissionInfo.
/**
	 * Returns the string encoding of this {@code PermissionInfo} in a form
	 * suitable for restoring this {@code PermissionInfo}.
	 * 
	 * <p>
	 * The encoded format is:
	 * 
	 * <pre>
	 * (type)
	 * </pre>
	 * 
	 * or
	 * 
	 * <pre>
	 * (type &quot;name&quot;)
	 * </pre>
	 * 
	 * or
	 * 
	 * <pre>
	 * (type &quot;name&quot; &quot;actions&quot;)
	 * </pre>
	 * 
	 * where <i>name</i> and <i>actions</i> are strings that must be encoded for
	 * proper parsing. Specifically, the {@code "},{@code \}, carriage return,
	 * and line feed characters must be escaped using {@code \"}, {@code \\},
	 * {@code \r}, and {@code \n}, respectively.
	 * 
	 * <p>
	 * The encoded string contains no leading or trailing whitespace characters.
	 * A single space character is used between <i>type</i> and
	 * &quot;<i>name</i>&quot; and between &quot;<i>name</i>&quot; and
	 * &quot;<i>actions</i>&quot;.
	 * 
	 * @return The string encoding of this {@code PermissionInfo}.
	 */
	public final String getEncoded() {
		StringBuilder output = new StringBuilder(
				8 + type.length() + ((((name == null) ? 0 : name.length())
						+ ((actions == null) ? 0 : actions.length())) << 1));
		output.append('(');
		output.append(type);
		if (name != null) {
			output.append(" \"");
			escapeString(name, output);
			if (actions != null) {
				output.append("\" \"");
				escapeString(actions, output);
			}
			output.append('\"');
		}
		output.append(')');
		return output.toString();
	}

	
Returns the string representation of this PermissionInfo. The string is created by calling the getEncoded method on this PermissionInfo. 
Returns:The string representation of this PermissionInfo.
/**
	 * Returns the string representation of this {@code PermissionInfo}. The
	 * string is created by calling the {@code getEncoded} method on this
	 * {@code PermissionInfo}.
	 * 
	 * @return The string representation of this {@code PermissionInfo}.
	 */
	@Override
	public String toString() {
		return getEncoded();
	}

	
Returns the fully qualified class name of the permission represented by this PermissionInfo. 
Returns:The fully qualified class name of the permission represented by this PermissionInfo.
/**
	 * Returns the fully qualified class name of the permission represented by
	 * this {@code PermissionInfo}.
	 * 
	 * @return The fully qualified class name of the permission represented by
	 *         this {@code PermissionInfo}.
	 */
	public final String getType() {
		return type;
	}

	
Returns the name of the permission represented by this PermissionInfo. 
Returns:The name of the permission represented by this PermissionInfo, or null if the permission does not have a name.
/**
	 * Returns the name of the permission represented by this
	 * {@code PermissionInfo}.
	 * 
	 * @return The name of the permission represented by this
	 *         {@code PermissionInfo}, or {@code null} if the permission does
	 *         not have a name.
	 */
	public final String getName() {
		return name;
	}

	
Returns the actions of the permission represented by this PermissionInfo. 
Returns:The actions of the permission represented by this PermissionInfo, or null if the permission does not have any actions associated with it.
/**
	 * Returns the actions of the permission represented by this
	 * {@code PermissionInfo}.
	 * 
	 * @return The actions of the permission represented by this
	 *         {@code PermissionInfo}, or {@code null} if the permission does
	 *         not have any actions associated with it.
	 */
	public final String getActions() {
		return actions;
	}

	
Determines the equality of two PermissionInfo objects. This method checks that specified object has the same type, name and actions as this PermissionInfo object. 
Params:
  • obj – The object to test for equality with this PermissionInfo object.
Returns:true if obj is a PermissionInfo, and has the same type, name and actions as this PermissionInfo object; false otherwise.
/**
	 * Determines the equality of two {@code PermissionInfo} objects.
	 * 
	 * This method checks that specified object has the same type, name and
	 * actions as this {@code PermissionInfo} object.
	 * 
	 * @param obj The object to test for equality with this
	 *        {@code PermissionInfo} object.
	 * @return {@code true} if {@code obj} is a {@code PermissionInfo}, and has
	 *         the same type, name and actions as this {@code PermissionInfo}
	 *         object; {@code false} otherwise.
	 */
	@Override
	public boolean equals(Object obj) {
		if (obj == this) {
			return true;
		}
		if (!(obj instanceof PermissionInfo)) {
			return false;
		}
		PermissionInfo other = (PermissionInfo) obj;
		if (!type.equals(other.type) || ((name == null) ^ (other.name == null)) || ((actions == null) ^ (other.actions == null))) {
			return false;
		}
		if (name != null) {
			if (actions != null) {
				return name.equals(other.name) && actions.equals(other.actions);
			} else {
				return name.equals(other.name);
			}
		} else {
			return true;
		}
	}

	
Returns the hash code value for this object.

Returns:A hash code value for this object.
/**
	 * Returns the hash code value for this object.
	 * 
	 * @return A hash code value for this object.
	 */
	@Override
	public int hashCode() {
		int h = 31 * 17 + type.hashCode();
		if (name != null) {
			h = 31 * h + name.hashCode();
			if (actions != null) {
				h = 31 * h + actions.hashCode();
			}
		}
		return h;
	}

	
This escapes the quotes, backslashes, \n, and \r in the string using a
backslash and appends the newly escaped string to a StringBuilder.

/**
	 * This escapes the quotes, backslashes, \n, and \r in the string using a
	 * backslash and appends the newly escaped string to a StringBuilder.
	 */
	private static void escapeString(String str, StringBuilder output) {
		int len = str.length();
		for (int i = 0; i < len; i++) {
			char c = str.charAt(i);
			switch (c) {
				case '"' :
				case '\\' :
					output.append('\\');
					output.append(c);
					break;
				case '\r' :
					output.append("\\r");
					break;
				case '\n' :
					output.append("\\n");
					break;
				default :
					output.append(c);
					break;
			}
		}
	}

	
Takes an encoded character array and decodes it into a new String.

/**
	 * Takes an encoded character array and decodes it into a new String.
	 */
	private static String unescapeString(char[] str, int begin, int end) {
		StringBuilder output = new StringBuilder(end - begin);
		for (int i = begin; i < end; i++) {
			char c = str[i];
			if (c == '\\') {
				i++;
				if (i < end) {
					c = str[i];
					switch (c) {
						case '"' :
						case '\\' :
							break;
						case 'r' :
							c = '\r';
							break;
						case 'n' :
							c = '\n';
							break;
						default :
							c = '\\';
							i--;
							break;
					}
				}
			}
			output.append(c);
		}

		return output.toString();
	}
}