Class PermissionUtils
public class PermissionUtils
{
// Methods
public static String ArraytoString (Object o);
public static IntRanges[] combineArraysOfIntRanges (
IntRanges[] r1, IntRanges[] r2);
public static String[] combineArraysOfStrings (String[] list1,
String[] list2);
public static WildcardExpression combinePatterns (
WildcardExpression spec1, WildcardExpression spec2);
public static Vector combineVectorsOfIntRanges (Vector v1, Vector
v2);
public static int compareArraysOfStrings (String[] list1,
String[] list2, int cmp);
public static int compareBooleans (boolean f1, boolean f2,
int prevcmp);
public static int compareFlags (int flags1, int flags2, int mask,
int prevcmp);
public static int compareIncludeExcludePatterns (
WildcardExpression include1, WildcardExpression exclude1,
WildcardExpression include2, WildcardExpression exclude2,
int cmp );
public static int compareInclusiveBooleans (boolean f1,
boolean f2, int prevcmp);
public static int compareInclusiveFlags (int flags1, int flags2,
int mask, int prevcmp);
public static int compareLimits (long limit1, long limit2,
int prevcmp);
public static String ComparisonResulttoString (int cmp);
public static Vector concatVectors (Vector v1, Vector v2);
public static IntRanges[] copyArrayOfIntRanges (IntRanges[] ap);
public static Vector[] copyArrayOfVectorsOfIntRanges (
Vector[] av);
public static WildcardExpression[] copyArrayOfWildcardExpressions
(WildcardExpression[] ap);
public static Vector copyVectorOfIntRanges (Vector v);
public static int invertComparisonResult (int cmp);
public static int mergeComparisonResults (int cmp1, int cmp2);
public static String[] parseStringIntoArray(String str,
String delims);
}
This class provides routines used by the permission classes. It includes several methods that assist with copying, comparing, and combining assorted types of elements of permissions. Three categories of functions describe the methods in this class:
- Deep copy helpers for implementing IPermission.copy. The object returned is completely independent of the original, and changes made to the original or to the copy will not affect the other. In other words, containers return a new container, containing a clone of each element; elements that are containers recursively copy their elements.
- Comparison helpers for implementing compareSet. These helper methods include methods for comparing simple types and String arrays. The mergeComparisonResults method is also included for combining the results for individual aspects of a permission into a single result for the entire permission.
- Combining helpers for implementing IPermission.combine. With one exception, which is the concatVectors method, all of these methods return the concatenation of deep copies of two objects.
public static String ArraytoString (Object o);
Recursively constructs a string representation for an array of any type and for each of its elements.
Return Value:
Returns a string representation of the specified array.
Parameter | Description |
o
| The array to construct the string representation of. The component type can be any class type or any primitive type.
|
Exceptions:
IllegalArgumentException
if the specified object is not an array.
public static IntRanges[] combineArraysOfIntRanges (IntRanges[] r1,
IntRanges[] r2);
Copies two arrays of IntRanges into a new array. The elements are copied using IntRanges.copy.
Return Value:
Returns a new array containing copies of the elements of r1, followed by copies of the elements of r2.
Parameter | Description |
r1
| The first array of IntRanges, or null.
|
r2
| The second array of IntRanges, or null.
|
public static String[] combineArraysOfStrings (String[] list1,
String[] list2);
Copies two arrays of strings into a new list. The strings in list1 are copied first into the new list, followed by the strings in list2.
Return Value:
Returns a new list containing copies of the strings in list1, followed by copies of the strings in list2.
Parameter | Description |
list1
| The first list of strings, or null.
|
list2
| The second list of strings, or null.
|
public static WildcardExpression combinePatterns (WildcardExpression spec1,
WildcardExpression spec2);
Combines two WildcardExpression objects. The resulting expression will first match any strings that are matched by the first expressions, followed by the strings matched by the second expression. The combined expression is independent of the original expressions; changes to the combined expression will not affect the originals and vice versa.
Return Value:
Returns a new expression, matching any strings matched by spec1 or spec2, in that order.
Parameter | Description |
spec1
| The first source expression to combine, or null.
|
spec2
| The second source expression to combine, or null.
|
public static Vector combineVectorsOfIntRanges (Vector v1, Vector v2);
Combines two vectors containing IntRanges objects.
Return Value:
Returns a new vector containing the elements of v1, followed by the elements of v2.
Parameter | Description |
v1
| The first Vector of IntRanges, or null.
|
v2
| The second Vector of IntRanges, or null.
|
public static int compareArraysOfStrings (String[] list1, String[] list2,
int cmp);
Compares two arrays of strings.
Return Value:
Returns a new comparison result, merged with the specified previous comparison result using mergeComparisonResults.
Parameter | Description |
list1
| The first list of strings, or null.
|
list2
| The second list of strings, or null.
|
cmp
| A previous comparison result for other resources of the permissions. For the first resource of a permission, this is typically SetComparison.EMPTY.
|
public static int compareBooleans (boolean f1, boolean f2, int prevcmp);
Compares two booleans. Each boolean represents access to resources that are independent of the other resources of the permissions.
Return Value:
Returns a new comparison result, merged with the previous comparison result using mergeComparisonResults.
The following table shows how booleans are compared by this method.
Parameter | Description |
f1
| If true, access to the resource in the first permission is granted; otherwise, access is denied.
|
f2
| If true, access to the resource in the second permission is granted; otherwise, access is denied.
|
prevcmp
| A previous comparison result for other resources of the permissions. For the first resource of a permission, this is typically SetComparison.EMPTY.
|
public static int compareFlags (int flags1, int flags2, int mask,
int prevcmp);
Compares two sets of flags. Each flag represents access to resources that are independent of other resources of the permissions. The flags to be compared are selected by a bitmask and are compared as a unit.
Return Value:
Returns a new comparison result, merged with the previous comparison result using mergeComparisonResults.
The following table shows the results of comparing different sets of flags.
Parameter | Description |
flags1
| The flags that determine access to resources in the first permission
|
flags2
| The flags that determine access to resources in the second permission.
|
mask
| A bitmask that is combined with the flags (using the logical AND operator (&)) to determine which resources are to be compared as a unit.
|
prevcmp
| A previous comparison result for other resources of the permissions. For the first resource of a permission, this is typically SetComparison.EMPTY.
|
public static int compareIncludeExcludePatterns (
WildcardExpression include1, WildcardExpression exclude1,
WildcardExpression include2, WildcardExpression exclude2, int cmp );
Compares sets of resources specified by include/exclude patterns. The include pattern specifies resources for which access will be granted, and the exclude rules specify resources that are to be excluded from the include rules.
The following table lists several include/exclude pairs and specifies the result obtained by comparing each pair using this method.
Pair 1
|
Pair 2
|
Result
|
include * exclude *.txt
|
include *
|
SUBSET
|
include * exclude *.txt
|
include *.doc
|
SUPERSET
|
include * exclude *.txt
|
include * exclude *.doc
|
OVERLAP
|
include * exclude *.txt
|
include * exclude foo.txt
|
SUBSET
|
include * exclude *.txt
|
include *.txt
|
DISJOINT
|
Return Value:
Returns a new comparison result, merged with the previous comparison result using mergeComparisonResults.
Parameter | Description |
include1
| For the first permission, the patterns that specify resources to grant access to, or null.
|
exclude1
| For the first permission, the patterns that specify resources to exclude from the include rules.
|
include2
| For the second permission, the patterns that specify resources to grant access to.
|
exclude2
| For the second permission, the patterns that specify resources to exclude from the include rules.
|
cmp
| A previous comparison result for other resources of the permissions. For the first resource of a permission, this is typically SetComparison.EMPTY.
|
Exceptions:
IllegalArgumentException
if any of the exclude rules are not a subset of one or more of the include rules, or if the exclude rules are specified without the include rules.
public static int compareInclusiveBooleans (boolean f1, boolean f2,
int prevcmp);
Compares two booleans that represent inclusive access to resources. A boolean value of false means that access to resources may be granted; a value of true means that more resources will be granted. Typically, this comparator is used only when the possession of the permission itself has meaning, because it becomes impossible to determine DISJOINT or EMPTY permissions after use of this comparator.
Return Value:
Returns a new comparison result, merged with the previous comparison result using mergeComparisonResults.
The following table shows how booleans are compared by this method.
Parameter | Description |
f1
| A flag that specifies the type of access to the resource in the first permission. If false, access to the resource is not denied; if true, more privileged access to the resource is granted.
|
f2
| A flag that specifies the type of access to the resource in the second permission. If false, access to the resource is not denied; if true, more privileged access to the resource is granted.
|
prevcmp
| A previous comparison result for other resources of the permissions. For the first resource of a permission, this is typically SetComparison.EMPTY.
|
public static int compareInclusiveFlags (int flags1, int flags2, int mask,
int prevcmp);
Compares two sets of flags that represent inclusive access to resources. The flags to be compared are selected by a bitmask and are compared as a unit. A clear flag means that access to resources may be granted; a set flag means that more resources will be granted. Typically, this comparator is only used when the possession of the permission itself has meaning, because it becomes impossible to determine DISJOINT or EMPTY permissions after use of this comparator.
Return Value:
Returns a new comparison result, merged with the previous comparison result using mergeComparisonResults.
The following table shows how flags are compared by this method.
Parameter | Description |
flags1
| The flags that specify the type of access to the resource in the first permission. If bits are clear, access to the resource is not denied; if bits are set, more privileged access to the resource is granted.
|
flags2
| The flags that specify the type of access to the resource in the second permission. If bits are clear, access to the resource is not denied; if bits are set, more privileged access to the resource is granted.
|
mask
| A bitmask that is combined with the flags (using the logical AND operator (&)) to determine which resources to compare as a unit.
|
prevcmp
| A previous comparison result for other resources of the permissions. For the first resource of a permission, this is typically SetComparison.EMPTY.
|
public static int compareLimits (long limit1, long limit2, int prevcmp);
Compares two positive numerical limits. A higher value is considered more privileged.
Return Value:
Returns a new comparison result, merged with the previous comparison result using mergeComparisonResults.
The following table shows how limits are compared by this method.
Parameter | Description |
limit1
| The first numerical limit.
|
limit2
| The second numerical limit.
|
prevcmp
| A previous comparison result.
|
public static String ComparisonResulttoString (int cmp);
Converts com.ms.util.SetComparison results to a string format.
Return Value:
Returns one of the following result strings:
public static Vector concatVectors (Vector v1, Vector v2);
Combines two vectors by copying their contents into a new Vector.
Caution This is not a deep copy. It is only safe for use with the IPermission.combine method when the element type is immutable, such as the String type.
Return Value:
Returns a new vector containing the elements of v1, followed by the elements of v2. If either of the vectors are null, the other non-null vector is returned.
Parameter | Description |
v1
| The first vector to combine, or null.
|
v2
| The second vector to combine, or null.
|
public static IntRanges[] copyArrayOfIntRanges (IntRanges[] ap);
Returns a deep copy of an array of IntRanges objects. Each element is copied using the IntRanges.copy method.
Return Value:
Returns null if ap is null; otherwise, returns a new array that contains copies of the elements of ap.
Parameter | Description |
ap
| An array of IntRanges, or null. The array can contain null elements.
|
public static Vector[] copyArrayOfVectorsOfIntRanges (Vector[] av);
Returns a deep copy of an array of Vectors containing IntRanges objects. Each Vector is copied using copyVectorOfIntRanges.
Return Value:
Returns null if av is null; otherwise, a new array of vectors is returned that contains new vectors with copies of their elements.
Parameter | Description |
av
| An array of Vectors, or null. The elements of the array or the vectors can be null.
|
public static WildcardExpression[] copyArrayOfWildcardExpressions (
WildcardExpression[] ap);
Returns a deep copy of an array of WildcardExpressions. Each expression is copied using WildcardExpression.copy.
Return Value:
Returns null if ap is null; otherwise, a new array is returned that contains copies of the elements of ap.
public static Vector copyVectorOfIntRanges (Vector v);
Returns a deep copy of a vector of IntRanges objects. Each element is copied using the IntRanges.copy method.
Return Value:
Returns a new Vector object containing copies of the elements of v, or returns null if v is null.
Parameter | Description |
v
| The vector of IntRanges to copy, or null. The vector can contain null elements.
|
public static int invertComparisonResult (int cmp);
Inverts comparison results.
Return Value:
Returns the inverted comparison result, described as follows:
Any other result is not affected by this method and is simply returned. Notice that EQUAL and DISJOINT are not inverted by this method.
Parameter | Description |
cmp
| The result to be inverted. It can be any of the following comparison results of the compare method:
|
public static int mergeComparisonResults (int cmp1, int cmp2);
Merges the comparison results from SetComparison.compareSet of two different sets into one, as though they were part of the same set.
Return Value:
Returns the merged comparison result.
Parameter | Description |
cmp1
| The first comparison result.
|
cmp2
| The second comparison result.
|
public static String[] parseStringIntoArray(String str,String delims);
Splits a string into an array of strings at the specified delimiters.
Return Value:
Returns the string that results from parsing.
Parameter | Description |
str
| The string that is parsed.
|
delims
| The delimiters to use when parsing.
|