Class FileIOPermission

public class FileIOPermission implements IPermission, 
            IEncodablePermission, IAdjustablePermission
{
  // Constructors
  public FileIOPermission();

  // Methods
  public void addDeleteableFile (String filename,
        boolean allowed) throws IOException;
  public void addDeleteableFiles (String pattern, boolean allow);
  public void addFile (int access, String filename,
        boolean allowed) throws IOException;
  public void addFiles (int access, WildcardExpression newspec,
        boolean allowed);
  public void addReadableFile (String filename,
        boolean allowed) throws IOException;
  public void addReadableFiles (String pattern, boolean allow);
  public void addWriteableFile(String filename,
        boolean allowed) throws IOException;
  public void addWriteableFiles (String pattern, boolean allow);
  public void adjustPermission (String tag, Object adjustment);
  public void check(Object param) throws SecurityException;
  public IPermission combine(IPermission source2);
  public int compareSet(Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public boolean getCanReadFromFileURLCodebase();
  public WildcardExpression getDeleteableFiles (boolean allowed);
  public WildcardExpression getFiles (int access, boolean allowed);
  public WildcardExpression getReadableFiles (boolean allowed);
  public WildcardExpression getWriteableFiles (boolean allowed);
  public String mapFormat(String format);
  public void reset();
  public void setCanReadFromFileURLCodebase(boolean flag);
  public String[] supportedFormats();
  public String toString();
}

This class represents a permission that controls the ability to access files. The StandardSecurityManager checks for this permission type when performing the checkRead, checkWrite, and checkDelete operations.

The permission distinguishes between the following three different types of file I/O access.

FileIORequest.READ

Read-only access to the contents of the file or access to information about the file, such as its length or last modification time.

FileIORequest.WRITE

Write access to the contents of the file or access to change information about the file, such as its name.

FileIORequest.DELETE

The ability to delete the file.

The specific files that the permission instance allows for each of these access types are defined by a pair of include/exclude patterns.

When permissions are checked, the requested filename is expanded to its full form using java.io.File.getCanonicalPath, so the permission objects must contain full path specifications. The addReadableFile, addWriteableFile, and addDeleteableFile methods can be used to convert a single filename to its full form and add it to the permission.

This class implements the IPermission, the IEncodablePermission, and the IAdjustablePermission interfaces.

Also see com.ms.security.permissions.FileIORequest

Constructors

FileIOPermission

public FileIOPermission();

Creates a new FileIOPermission instance.

Remarks:

The new instance does not allow any file I/O operations.

Methods

addDeleteableFile

public void addDeleteableFile (String filename, boolean allowed)
        throws IOException;

Adds a file to the set, either allowing or denying that file for delete access.

Return Value:

No return value.

Parameter	Description
filename	The name of the file to add to the permission.
allowed	The flag that indicates whether you are allowing or denying the file. If the value is true, the file is allowed; otherwise, the file is denied.

Exceptions:

IOException if an error occurs while getting the full name of the file.

addDeleteableFiles

public void addDeleteableFiles (String pattern, boolean allow);

Adds a pattern that specifies a set of files that are allowed or denied for deleting.

Return Value:

No return value.

Parameter	Description
pattern	The string that indicates which files to allow or deny. It must be of the form accepted by a WildcardExpression with the ESCAPED flag enabled.
allow	The flag that indicates whether you are allowing or denying the files specified by the pattern. If the value is true, the files are allowed. Otherwise, the files are denied. You can deny files only if the file was previously allowed.

addFile

public void addFile (int access, String filename, boolean allowed)
        throws IOException;

Adds a specific file to the permission, either allowing or denying that file for the specified access types. The file is expanded to its fully qualified form using the java.io.File.getCanonicalPath method.

Return Value:

No return value.

Parameter	Description
access	An access type that is one of the following values: FileIORequest.READ, FileIORequest.WRITE, or FileIORequest.DELETE.
filename	The name of the file to add to the permission.
allowed	The flag that indicates whether you are allowing or denying the file for the specified access type. If the value is true, the file is allowed; otherwise, the file is denied.

Exceptions:

IOException if an error occurs while getting the full name of the file.

addFiles

public void addFiles (int access, WildcardExpression newspec,
        boolean allowed);

Adds a set of files to this permission, either allowing or denying those files for the specified access type. The files to be added are specified as a WildcardExpression object.

Return Value:

No return value.

Parameter	Description
access	An access type that is one of the following values: FileIORequest.READ, FileIORequest.WRITE, or FileIORequest.DELETE.
newspec	The wildcard expression that indicates the files to add.
allowed	The flag that indicates whether you are allowing or denying the file for the specified access type. If the value is true, the files are allowed; otherwise, they are denied.

addReadableFile

public void addReadableFile (String filename, boolean allowed)
        throws IOException;

Adds a file to the set, either allowing or denying that file for read access. Calling this method is equivalent to the following call.

addFile(FileIORequest.READ,filename,allowed)

Return Value:

No return value.

Parameter	Description
filename	The name of the file to add to the permission.
allowed	The flag that indicates whether you are allowing or denying the file. If the value is true, the file is allowed; otherwise, the file is denied.

Exceptions:

IOException if an error occurs while getting the full name of the file.

addReadableFiles

public void addReadableFiles (String pattern, boolean allow);

Adds a pattern that specifies a set of files that are allowed or denied for reading.

Return Value:

No return value.

Parameter	Description
pattern	The string that indicates which files to allow or deny. It must be of the form accepted by a WildcardExpression with the ESCAPED flag enabled.
allow	The flag that indicates whether you are allowing or denying the files specified by the pattern. If the value is true, the files are allowed. Otherwise, the files are denied. You can deny files only if the file was previously allowed.

addWriteableFile

public void addWriteableFile(String filename, boolean allowed)
        throws IOException;

Adds a file to the set, either allowing or denying that file for write access. Calling this method is equivalent to the following call.

addFile(FileIORequest.WRITE,filename,allowed)

Return Value:

No return value.

Parameter	Description
filename	The name of the file to add to the permission.
allowed	The flag that indicates whether you are allowing or denying the file. If the value is true, the file is allowed; otherwise, the file is denied.

Exceptions:

IOException if an error occurs while getting the full name of the file.

addWriteableFiles

public void addWriteableFiles (String pattern, boolean allow);

Adds a pattern that specifies a set of files that are allowed or denied for writing.

Return Value:

No return value.

Parameter	Description
pattern	The string that indicates which files to allow or deny. It must be of the form accepted by a WildcardExpression with the ESCAPED flag enabled.
allow	The flag that indicates whether you are allowing or denying the files specified by the pattern. If the value is true, the files are allowed. Otherwise, the files are denied. You can deny files only if the file was previously allowed.

adjustPermission

public void adjustPermission (String tag, Object adjustment);

Adjusts the permission object with some run-time state.

Return Value:

No return value.

Parameter	Description
tag	The adjustment type. Every type except "codebase" is ignored.
adjustment	This parameter must be an instance of java.net.URL for the "codebase" tag.

Remarks:

The FileIOPermission only responds to the "codebase" adjustment type, and expects the adjustment parameter to be of type URL in that case. All other adjustment types are ignored.

If the URL is a file:// URL and if the permission allows reading from file:// URL codebases, this method adds read access for the "codebase" directory (and everything below it) to the permission object.

check

public void check(Object param) throws SecurityException;

Determines if the specified file I/O operation is allowed by this permission object.

Return Value:

No return value.

Parameter	Description
param	The security request parameter. It must be an instance of the FileIORequest class.

Exceptions:

SecurityException if this permission does not allow the specified file I/O operation.

combine

public IPermission combine(IPermission source2);

Creates and returns a new FileIOPermission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects that it was constructed from.

Return Value:

Returns the resulting FileIOPermission object.

Parameter	Description
source2	The FileIOPermission object to combine with.

Exceptions:

IllegalArgumentException if the specified object to combine with is not an instance of FileIOPermission.

compareSet

public int compareSet(Object target);

Compares the FileIOPermission instance with a specified permission object.

Return Value:

Returns one of the following constants:

• DISJOINT
• EMPTY
• OVERLAP
• EQUAL
• SUBSET
• SUPERSET
• EMPTY_SUBSET
• EMPTY_SUPERSET

Parameter	Description
target	The permission object that the FileIOPermission instance is compared with.

copy

public IPermission copy();

Retrieves a copy of the FileIOPermission instance.

Return Value:

Returns the copy of the FileIOPermission instance.

decode

public boolean decode(String tag, InputStream data);

Decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Return Value:

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameter	Description
tag	The encoding type identifier.
data	The raw data to construct the object from. The type of data is specified by the tag parameter.

encode

public boolean encode(String tag, OutputStream out);

Encodes the contents of this permission object and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Return Value:

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameter	Description
tag	The encoding type identifier.
out	The output stream to send the encoded data to.

getCanReadFromFileURLCodebase

public boolean getCanReadFromFileURLCodebase();

Returns the flag that controls whether classes that possess this permission should have read access to the directory that they were loaded from, if that location is a file:// URL.

Return Value:

Returns true if the permission allows reading from file:// URL codebases; otherwise, returns false.

getDeleteableFiles

public WildcardExpression getDeleteableFiles (boolean allowed);

Obtains a pattern that matches all files that are permitted or all files that are explicitly prohibited for delete access. The allowed flag indicates whether you want to obtain the pattern that matches files that have been explicitly allowed or explicitly denied.

Return Value:

Returns the WildcardExpression that matches the requested files.

Parameter	Description
allowed	The flag that indicates whether you want to obtain the pattern for explicitly allowed files or explicitly denied files. If true, the method returns a pattern that matches all files that are explicitly allowed; otherwise, the method returns a pattern that matches all files that are explicitly denied.

getFiles

public WildcardExpression getFiles (int access, boolean allowed);

Retrieves a WildcardExpression object that indicates all the files that this permission object matches for the specified access type.

Return Value:

Returns the wildcard expression that indicates the matching files.

Parameter	Description
access	An access type that is one of the following values: FileIORequest.READ, FileIORequest.WRITE, or FileIORequest.DELETE.
allowed	The flag that indicates whether this method retrieves the pattern that matches files that have been explicitly allowed or explicitly denied. If true, this method returns the pattern for files that have been explicitly allowed; otherwise, it returns the pattern for files that have been explicitly denied.

getReadableFiles

public WildcardExpression getReadableFiles (boolean allowed);

Obtains a pattern that matches all files that are permitted or all files that are explicitly prohibited for read access. The allowed flag indicates whether you want to obtain the pattern that matches files that have been explicitly allowed or explicitly denied.

Return Value:

Returns the WildcardExpression that matches the requested files.

Parameter	Description
allowed	The flag that indicates whether you want to obtain the pattern for explicitly allowed files or explicitly denied files. If true, the method returns a pattern that matches all files that are explicitly allowed; otherwise, the method returns a pattern that matches all files that are explicitly denied.

getWriteableFiles

public WildcardExpression getWriteableFiles (boolean allowed);

Obtains a pattern that matches all files that are permitted or all files that are explicitly prohibited for write access. The allowed flag indicates whether you want to obtain the pattern that matches files that have been explicitly allowed or explicitly denied.

Return Value:

Returns the WildcardExpression that matches the requested files.

Parameter	Description
allowed	The flag that indicates whether you want to obtain the pattern for explicitly allowed files or explicitly denied files. If true, the method returns a pattern that matches all files that are explicitly allowed; otherwise, the method returns a pattern that matches all files that are explicitly denied.

mapFormat

public String mapFormat(String format);

Retrieves a permission-specific tag when given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Return Value:

Returns the permission-specific tag that corresponds to the specified format.

Parameter	Description
format	The encoding format to retrieve the tag for.

reset

public void reset();

Resets the permission state to empty. This is a state in which the object allows no file I/O access.

Return Value:

No return value.

setCanReadFromFileURLCodebase

public void setCanReadFromFileURLCodebase(boolean flag);

Sets the flag that controls whether classes that possess this permission should have read access to the directory that they were loaded from, if that location is a file:// URL.

Return Value:

No return value.

Parameter	Description
flag	The value that indicates whether this permission should allow reading from the "codebase" directory for file:// URLs. If true, the flag will be set so that reading is allowed; otherwise, the flag is set so that reading is not allowed.

Remarks:

If the flag is set to true, a later "codebase" adjustment by using the adjustPermission method will include the "codebase" directory in the set of files that can be read by this permission. If this flag is false, a later call to the adjustPermission method will do nothing.

supportedFormats

public String[] supportedFormats();

Returns the encoding formats that the permission type supports.

Return Value:

Returns an array of the supported format identifiers.

toString

public String toString();

Retrieves a textual representation of the permission object.

Return Value:

Returns the string representation of the permission object.