Class PermissionTreeOutput

public class PermissionTreeOutput extends OutputStream
{
  // Constructors
  public PermissionTreeOutput();

  // Methods
  public void addField();
  public void addNode(int level);
  public void addPermission(int level, IPermission perm);
  public void addPermission(int level, IPermission perm,
        boolean highRisk);
  public int count();
  public String dump();
  public void flush() throws IOException;
  public void increase();
  public int[] nodeLevel();
  public char[][] nodeValue();
  public int[] riskFactor();
  public void setStartLevel(int sl);  
  public int startLevel();
  public String toString();
  public void writeField(String s) throws IOException;
  public void writeNode(String s, int level) throws IOException;
  public void writePermission(String s, int level,
        IPermission perm) throws IOException;
  public void writePermission(String s, int level,
        IPermission perm, boolean highRisk) throws IOException;
}

This class is used to create a tree representation of the permissions. In the security dialog boxes for Microsoft® Internet Explorer version 4.01, the permissions are displayed in the form of a tree control decorated with icons that indicate risk factors.

This class is used with the IEncodablePermission.encode method and the EncodeFormats.DISPLAYTREE format. To be displayed correctly in the security dialog boxes, a permission must be able to handle the EncodeFormat.DISPLAYTREE encoding type. The method that encodes the permission in DISPLAYTREE format should ensure that the OutputStream that receives the encoding is an instance of PermissionTreeOutput. Then the writePermission, writeNode, and writeField methods can be used to display information about the permission.

For instance, to add a title node for displaying the permission, you would use one of the writePermission methods. To add a sub-node heading for grouping related permission parameters, use the writeNode method. To add a leaf node that contains a specific parameter value, use the writeField method.

The following code would produce the tree displayed below. For brevity, only the mapFormat and encode methods are shown. However, your class would need to implement all the methods of the IEncodablePermission and IPermission interfaces.

public class MyPermission implements IPermission, IEncodablePermission
{
  private String treedisplaytag = "someString";
  private boolean param1;
  private int param2;
  private String param3;
   
  // Methods and data members are omitted for brevity.

  // Map the supported formats to tags.
  public String mapFormat(String format) 
  {
    if (format == EncodeFormats.DISPLAYTREE)
      return treedisplaytag;
  
    // else check to see if format represents
    // another supported format.
    ...
  }

  // Encode the permission to a supported format.
  public boolean encode(String tag, OutputStream myStream)
  {
    if (tag.equals(treedisplaytag)) 
    {
      return encodeTreeDisplay(myStream);      
    }

    // else check to see if the tag indicates
    // another supported encoding.
    ...
  } 

  // Encode the permission to the DISPLAYTREE format.
  boolean encodeTreeDisplay(OutputStream myStream)
  {
    if(myStream instanceof PermissionTreeOutput) 
    {
      PermissionTreeOutput tree = (PermissionTreeOutput) myStream;
      treeDisplay(tree);
      return true;
    }
    else return false;
  }

  // Write information to the tree.
  void treeDisplay(PermissionTreeOutput treeDisplay)
  {
    treeDisplay.writePermission("My Sample Permission", 0, this);
    treeDisplay.writeNode("Parameter 1", 1);
    treeDisplay.writeField("this.param1");
    treeDisplay.writeNode("Parameter 2", 1);
    treeDisplay.writeNode("Sub-Param 2", 2);
    treeDisplay.writeField("this.param2");
    treeDisplay.writeNode("Parameter 3", 1);
    .
    .
    .
  }
}

The displayed tree:

+--+ My Sample Permission
   | 
   +--+ Parameter 1 
   |  | 
   |  +--- X (the value of param1)
   | 
   +--+ Parameter 2
   |  | 
   |  +--+ Sub-Param 2 
   |     | 
   |     +--- Y (the value of sub-param2)
   |
   +--+ Parameter 3 
   . 
   . 
   . 

Also see com.ms.security.IEncodablePermission

OutputStream
  |
  +--PermissionTreeOutput

Constructors

PermissionTreeOutput

public PermissionTreeOutput();

Creates a new PermissionTreeOutput stream.

Methods

addField

public void addField();

Creates a leaf in the tree for displaying permission parameters.

Return Value:

No return value.

addNode

public void addNode(int level);

Creates a new node for displaying a header for permission data.

Return Value:

No return value.

Parameter	Description
level	The depth of the tree at which to place the node.

addPermission

public void addPermission(int level, IPermission perm);

Inserts a node for the specified permission and assigns it a risk value based on the default permission set.

Return Value:

No return value.

Parameter	Description
level	The depth of the tree at which to place the node.
perm	The permission that is being displayed at the current node.

addPermission

public void addPermission(int level, IPermission perm, 
        boolean highRisk);

Inserts a node for the specified permission. If the permission is not explicitly high risk, it is checked against the default sets to determine the risk factor.

Return Value:

No return value.

Parameter	Description
level	The depth of the tree at which to place the node.
perm	The permission that is being displayed at the current node.
highRisk	Specifies whether this permission should be flagged as high risk.

count

public int count();

Retrieves the number of elements in the tree.

Return Value:

Returns the number of elements in the tree.

setStartLevel

public void setStartLevel(int sl);

Sets the depth of the root node. Use this method when combining two (or more) separate trees into one tree.

Return Value:

No return value

Parameter	Description
sl	The depth of the root node.

startLevel

public int startLevel();

Retrieves the starting level of the root node.

Return Value:

Returns the depth of the root node.

toString

public String toString();

Converts the display tree to a String where the nodes and values are delimited by tabs and newline characters.

Return Value:

Returns a formatted text version of the tree.

writeField

public void writeField(String s) throws IOException;

Creates a leaf with the specified string as its value.

Return Value:

No return value.

Parameter	Description
s	The value to display at the leaf that is created.

Exceptions:

IOException if an error occurs while writing to the output stream.

writeNode

public void writeNode(String s, int level) throws IOException;

Creates a node with the specified string as the name for a new node in the display tree.

Return Value:

No return value.

Parameter	Description
s	The name of the node.
level	The depth of the tree at which to place the node.

Exceptions:

IOException if an error occurs while writing to the output stream.

writePermission

public void writePermission(String s, int level, 
        IPermission perm) throws IOException;

Creates a node with the specified string as the name for a new permission in the display tree.

Return Value:

No return value.

Parameter	Description
s	The name of the permission.
level	The depth of the tree at which to place the node.
perm	The permission that is being displayed at the current node.

Exceptions:

IOException if an error occurs while writing to the output stream.

writePermission

public void writePermission(String s, int level, IPermission perm,
        boolean highRisk) throws IOException;

Creates a node with the specified string as the name for a new permission in the display tree. In addition, the permission can be flagged as high risk.

Return Value:

No return value.

Parameter	Description
s	The name of the permission.
level	The depth of the tree at which to place the node.
perm	The permission that is being displayed at the current node.
highRisk	Specifies whether this permission should be flagged as high risk.

Exceptions:

IOException if an error occurs while writing to the output stream.