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.

Methods

ArraytoString

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.

combineArraysOfIntRanges

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.

combineArraysOfStrings

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.

combinePatterns

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.

combineVectorsOfIntRanges

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.

compareArraysOfStrings

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.

compareBooleans

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.

f1	f2	Result before merging
true	true	SetComparison.EQUAL
true	false	SetComparison.EMPTY_SUPERSET
false	true	SetComparison.EMPTY_SUBSET
false	false	SetComparison.EMPTY

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.

compareFlags

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.

flags1 & mask	flags2 & mask	Result before merging
nonzero	nonzero	SetComparison.EQUAL
nonzero	zero	SetComparison.EMPTY_SUPERSET
zero	nonzero	SetComparison.EMPTY_SUBSET
zero	zero	SetComparison.EMPTY

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.

compareIncludeExcludePatterns

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.

compareInclusiveBooleans

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.

f1	f2	Result before merging
true	true	SetComparison.EQUAL
true	false	SetComparison.SUPERSET
false	true	SetComparison.SUBSET
false	false	SetComparison.EQUAL

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.

compareInclusiveFlags

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.

flags1 & mask	flags2 & mask	Result before merging
nonzero	nonzero	SetComparison.EQUAL
nonzero	zero	SetComparison.SUPERSET
zero	nonzero	SetComparison.SUBSET
zero	zero	SetComparison.EQUAL

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.

compareLimits

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.

limit1	limit2	Result before merging
0	0	SetComparison.EMPTY
>0	0	SetComparison.EMPTY_SUPERSET
0	>0	SetComparison.EMPTY_SUBSET
>limit2	>0	SetComparison.SUPERSET
>0	>limit1	SetComparison.SUBSET
=limit2	=limit1	SetComparison.EQUAL

Parameter	Description
limit1	The first numerical limit.
limit2	The second numerical limit.
prevcmp	A previous comparison result.

ComparisonResulttoString

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:

• "empty" (EMPTY)
• "equal" (EQUAL)
• "disjoint" (DISJOINT)
• "overlap" (OVERLAP)
• "inclusive subset" (SUBSET)
• "inclusive superset" (SUPERSET)
• "empty subset" (EMPTY_SUBSET)
• "empty superset" (EMPTY_SUPERSET)

Parameter	Description
cmp	A comparison result from the SetComparison.compareSet method.

concatVectors

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.

copyArrayOfIntRanges

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.

copyArrayOfVectorsOfIntRanges

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.

copyArrayOfWildcardExpressions

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.

Parameter	Description
ap	An array of WildcardExpressions, or null.

copyVectorOfIntRanges

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.

invertComparisonResult

public static int invertComparisonResult (int cmp);

Inverts comparison results.

Return Value:

Returns the inverted comparison result, described as follows:

• If cmp is SUBSET, SUPERSET is returned.
• If cmp is SUPERSET, SUBSET is returned.
• If cmp is EMPTY_SUBSET, EMPTY_SUPERSET is returned.
• If cmp is EMPTY_SUPERSET, EMPTY_SUBSET is returned.

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: SetComparison.SUBSET returns SetComparison.SUPERSET. SetComparison.SUPERSET returns SetComparison.SUBSET. SetComparison.EMPTY_SUBSET returns SetComparison.EMPTY_SUPERSET. SetComparison.EMPTY_SUPERSET returns SetComparison.EMPTY_SUBSET.

mergeComparisonResults

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.

parseStringIntoArray

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.