Packages
 In this topic

*Methods

 

Packages   PreviousThis PackageNext
Package com.ms.security   Previous This
Package
Next

 


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.

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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

ParameterDescription
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

ParameterDescription
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.

ParameterDescription
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

ParameterDescription
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

ParameterDescription
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

ParameterDescription
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:

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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:

Any other result is not affected by this method and is simply returned. Notice that EQUAL and DISJOINT are not inverted by this method.

ParameterDescription
cmp The result to be inverted. It can be any of the following comparison results of the compare method:

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.

ParameterDescription
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.

ParameterDescription
str The string that is parsed.
delims The delimiters to use when parsing.

upnrm.gif © 1998 Microsoft Corporation. All rights reserved. Terms of use.