OpenJDK 1.22 · java.io.FilePermission · APIdia, the JavaDoc alternative

This class represents access to a file or directory. A FilePermission consists of a pathname and a set of actions valid for that pathname.

Pathname is the pathname of the file or directory granted the specified actions. A pathname that ends in "/*" (where "/" is the file separator character, File.separatorChar) indicates all the files and directories contained in that directory. A pathname that ends with "/-" indicates (recursively) all files and subdirectories contained in that directory. Such a pathname is called a wildcard pathname. Otherwise, it's a simple pathname.

A pathname consisting of the special token "<<ALL FILES>>" matches any file.

Note

A pathname consisting of a single "*" indicates all the files in the current directory, while a pathname consisting of a single "-" indicates all the files in the current directory and (recursively) all files and subdirectories contained in the current directory.

The actions to be granted are passed to the constructor in a string containing a list of one or more comma-separated keywords. The possible keywords are "read", "write", "execute", "delete", and "readlink". Their meaning is defined as follows:

read: read permission
write: write permission
execute: execute permission. Allows Runtime.exec to be called. Corresponds to SecurityManager.checkExec.
delete: delete permission. Allows File.delete to be called. Corresponds to SecurityManager.checkDelete.
readlink: read link permission. Allows the target of a symbolic link to be read by invoking the readSymbolicLink method.

The actions string is converted to lowercase before processing.

Be careful when granting FilePermissions. Think about the implications of granting read and especially write access to various files and directories. The "<<ALL FILES>>" permission with write action is especially dangerous. This grants permission to write to the entire file system. One thing this effectively allows is replacement of the system binary, including the JVM runtime environment.

Note

Code can always read a file from the same directory it's in (or a subdirectory of that directory); it does not need explicit permission to do so.

Field Summary

Modifier and Type	Field and Description
private String	actions the actions string.
private static final int	ALL All actions (read,write,execute,delete,readlink)
private transient boolean	allFiles
private static final FileSystem	builtInFS Use the platform's default file system to avoid recursive initialization issues when the VM is configured to use a custom file system provider.
private transient String	cpath
private static final Path	DASH_PATH
private static final int	DELETE Delete action.
private transient boolean	directory
private static final Path	DOTDOT_PATH
private static final Path	EMPTY_PATH
private static final int	EXECUTE Execute action.
private static final Path	here
private transient boolean	invalid
private transient int	mask
private static final int	NONE No actions.
private transient Path	npath
private transient Path	npath2
private static final int	READ Read action.
private static final int	READLINK Read link action.
private transient boolean	recursive
private static final char	RECURSIVE_CHAR
private static final long	serialVersionUID Hides java.security.Permission.serialVersionUID.
private static final char	WILD_CHAR
private static final int	WRITE Write action.

Constructor Summary

Access	Constructor and Description
private	FilePermission(String name, FilePermission input, Path npath, Path npath2, int mask, String actions) A private constructor that clones some and updates some, always with a different name.
public	FilePermission(String the pathname of the file/directory. path, String the action string. actions) Creates a new FilePermission object with the specified actions.
pack-priv	FilePermission(String the pathname of the file/directory. path, int the action mask to use. mask) Creates a new FilePermission object using an action mask.

Method Summary

Modifier and Type	Method and Description
private static Path	Returns: the alternative path, or null if cannot find one. altPath(Path a real path w/o "-" or "*" at the end, and not <>. in) Returns the alternative path as a Path object, i.e. absolute path for a relative one, or vice versa.
private static int	Returns: the depth in between containsPath(Path the expected outer path, normalized p1, Path the expected inner path, normalized p2) Returns the depth between an outer path p1 and an inner path p2.
public boolean	Returns: `true` if obj is a FilePermission, and has the same pathname and actions as this FilePermission object, `false` otherwise. equals(Object the object we are testing for equality with this object. obj) Implements abstract java.security.Permission.equals. Checks two FilePermission objects for equality.
private static String	Returns: the canonical string representation of the actions. getActions(int mask) Return the canonical string representation of the actions.
public String	Returns: the canonical string representation of the actions. getActions() Implements abstract java.security.Permission.getActions. Returns the "canonical string representation" of the actions.
private static int	Returns: the actions mask. getMask(String the action string. actions) Converts an actions String to an actions mask.
pack-priv int	Returns: the actions mask. getMask() Return the current action mask.
public int	Returns: a hash code value for this object. hashCode() Implements abstract java.security.Permission.hashCode. Returns the hash code value for this object.
public boolean	Returns: `true` if the specified permission is not `null` and is implied by this object, `false` otherwise. implies(Permission the permission to check against. p) Implements abstract java.security.Permission.implies. Checks if this FilePermission object "implies" the specified permission.
pack-priv boolean	Returns: the effective mask impliesIgnoreMask(FilePermission the FilePermission to check against. that) Checks if the Permission's actions are a proper subset of the this object's actions.
private void	init(int the actions mask to use. mask) initialize a FilePermission object.
public PermissionCollection	Returns: a new PermissionCollection object suitable for storing FilePermissions. newPermissionCollection() Overrides java.security.Permission.newPermissionCollection. Returns a new PermissionCollection object for storing FilePermission objects.
private void	readObject(ObjectInputStream s) readObject is called to restore the state of the FilePermission from a stream.
pack-priv FilePermission	Returns: a new object withNewActions(int the new actions effective) Create a cloned FilePermission with a different actions.
private void	writeObject(ObjectOutputStream s) WriteObject is called to save the state of the FilePermission to a stream.

Inherited from java.security.Permission:: checkGuard getName toString

Field Detail

actions	back to summary
private String actions the actions string.

ALL	back to summary
private static final int ALL All actions (read,write,execute,delete,readlink)

allFiles	back to summary
private transient boolean allFiles

builtInFS	back to summary
private static final FileSystem builtInFS Use the platform's default file system to avoid recursive initialization issues when the VM is configured to use a custom file system provider.

cpath	back to summary
private transient String cpath

DASH_PATH	back to summary
private static final Path DASH_PATH

DELETE	back to summary
private static final int DELETE Delete action.

directory	back to summary
private transient boolean directory

DOTDOT_PATH	back to summary
private static final Path DOTDOT_PATH

EMPTY_PATH	back to summary
private static final Path EMPTY_PATH

EXECUTE	back to summary
private static final int EXECUTE Execute action.

here	back to summary
private static final Path here

invalid	back to summary
private transient boolean invalid

mask	back to summary
private transient int mask

NONE	back to summary
private static final int NONE No actions.

npath	back to summary
private transient Path npath

npath2	back to summary
private transient Path npath2

READ	back to summary
private static final int READ Read action.

READLINK	back to summary
private static final int READLINK Read link action.

recursive	back to summary
private transient boolean recursive

RECURSIVE_CHAR	back to summary
private static final char RECURSIVE_CHAR

serialVersionUID	back to summary
private static final long serialVersionUID Hides java.security.Permission.serialVersionUID. Annotations @Serial

WILD_CHAR	back to summary
private static final char WILD_CHAR

WRITE	back to summary
private static final int WRITE Write action.

Constructor Detail

FilePermission	back to summary
private FilePermission(String name, FilePermission input, Path npath, Path npath2, int mask, String actions) A private constructor that clones some and updates some, always with a different name.

FilePermission back to summary

FilePermission	back to summary
public FilePermission(String path, String actions) Creates a new FilePermission object with the specified actions. path is the pathname of a file or directory, and actions contains a comma-separated list of the desired actions granted on the file or directory. Possible actions are "read", "write", "execute", "delete", and "readlink". A pathname that ends in "/" (where "/" is the file separator character, `File.separatorChar`) indicates all the files and directories contained in that directory. A pathname that ends with "/-" indicates (recursively) all files and subdirectories contained in that directory. The special pathname "<<ALL FILES>>" matches any file. A pathname consisting of a single "" indicates all the files in the current directory, while a pathname consisting of a single "-" indicates all the files in the current directory and (recursively) all files and subdirectories contained in the current directory. A pathname containing an empty string represents an empty path. Implementation Note In this implementation, the `jdk.io.permissionsUseCanonicalPath` system property dictates how the `path` argument is processed and stored. If the value of the system property is set to `true`, `path` is canonicalized and stored as a String object named `cpath`. This means a relative path is converted to an absolute path, a Windows DOS-style 8.3 path is expanded to a long path, and a symbolic link is resolved to its target, etc. If the value of the system property is set to `false`, `path` is converted to a `java.nio.file.Path` object named `npath` after `normalization`. No canonicalization is performed which means the underlying file system is not accessed. If an `InvalidPathException` is thrown during the conversion, this `FilePermission` will be labeled as invalid. In either case, the "*" or "-" character at the end of a wildcard `path` is removed before canonicalization or normalization. It is stored in a separate wildcard flag field. The default value of the `jdk.io.permissionsUseCanonicalPath` system property is `false` in this implementation. The value can also be set with a security property using the same name, but setting a system property will override the security property value. Parameters path:String the pathname of the file/directory. actions:String the action string. Exceptions IllegalArgumentException: if actions is `null`, empty, malformed or contains an action other than the specified possible actions

public FilePermission(String path, String actions)

Creates a new FilePermission object with the specified actions. path is the pathname of a file or directory, and actions contains a comma-separated list of the desired actions granted on the file or directory. Possible actions are "read", "write", "execute", "delete", and "readlink".

A pathname that ends in "/*" (where "/" is the file separator character, File.separatorChar) indicates all the files and directories contained in that directory. A pathname that ends with "/-" indicates (recursively) all files and subdirectories contained in that directory. The special pathname "<<ALL FILES>>" matches any file.

A pathname containing an empty string represents an empty path.

Implementation Note

In this implementation, the jdk.io.permissionsUseCanonicalPath system property dictates how the path argument is processed and stored.

If the value of the system property is set to true, path is canonicalized and stored as a String object named cpath. This means a relative path is converted to an absolute path, a Windows DOS-style 8.3 path is expanded to a long path, and a symbolic link is resolved to its target, etc.

If the value of the system property is set to false, path is converted to a java.nio.file.Path object named npath after normalization. No canonicalization is performed which means the underlying file system is not accessed. If an InvalidPathException is thrown during the conversion, this FilePermission will be labeled as invalid.

In either case, the "*" or "-" character at the end of a wildcard path is removed before canonicalization or normalization. It is stored in a separate wildcard flag field.

The default value of the jdk.io.permissionsUseCanonicalPath system property is false in this implementation.

The value can also be set with a security property using the same name, but setting a system property will override the security property value.

Parameters

path:String: the pathname of the file/directory.
actions:String: the action string.

Exceptions

IllegalArgumentException:: if actions is null, empty, malformed or contains an action other than the specified possible actions

FilePermission back to summary

FilePermission	back to summary
pack-priv FilePermission(String path, int mask) Creates a new FilePermission object using an action mask. More efficient than the FilePermission(String, String) constructor. Can be used from within code that needs to create a FilePermission object to pass into the `implies` method. Parameters path:String the pathname of the file/directory. mask:int the action mask to use.

pack-priv FilePermission(String path, int mask)

Creates a new FilePermission object using an action mask. More efficient than the FilePermission(String, String) constructor. Can be used from within code that needs to create a FilePermission object to pass into the implies method.

Parameters

path:String: the pathname of the file/directory.
mask:int: the action mask to use.

Method Detail

altPath	back to summary
private static Path altPath(Path in) Returns the alternative path as a Path object, i.e. absolute path for a relative one, or vice versa. Parameters in:Path a real path w/o "-" or "*" at the end, and not <>. Returns:Path the alternative path, or null if cannot find one.

altPath

back to summary

private static Path altPath(Path in)

Returns the alternative path as a Path object, i.e. absolute path for a relative one, or vice versa.

Parameters

in:Path: a real path w/o "-" or "*" at the end, and not <>.

Returns:Path

the alternative path, or null if cannot find one.

containsPath	back to summary
private static int containsPath(Path p1, Path p2) Returns the depth between an outer path p1 and an inner path p2. -1 is returned if - p1 does not contains p2. - this is not decidable. For example, p1="../x", p2="y". - the depth is not decidable. For example, p1="/", p2="x". This method can return 2 if the depth is greater than 2. Parameters p1:Path the expected outer path, normalized p2:Path the expected inner path, normalized Returns:int the depth in between

containsPath

back to summary

private static int containsPath(Path p1, Path p2)

Returns the depth between an outer path p1 and an inner path p2. -1 is returned if - p1 does not contains p2. - this is not decidable. For example, p1="../x", p2="y". - the depth is not decidable. For example, p1="/", p2="x". This method can return 2 if the depth is greater than 2.

Parameters

p1:Path: the expected outer path, normalized
p2:Path: the expected inner path, normalized

Returns:int

the depth in between

equals back to summary

equals	back to summary
public boolean equals(Object obj) Implements abstract java.security.Permission.equals. Checks two FilePermission objects for equality. Checks that obj is a FilePermission, and has the same pathname and actions as this object. Implementation Note More specifically, two pathnames are the same if and only if they have the same wildcard flag and their `cpath` (if `jdk.io.permissionsUseCanonicalPath` is `true`) or `npath` (if `jdk.io.permissionsUseCanonicalPath` is `false`) are equal. Or they are both "<<ALL FILES>>". When `jdk.io.permissionsUseCanonicalPath` is `false`, an invalid `FilePermission` does not equal to any object except for itself, even if they are created using the same invalid path. Parameters obj:Object the object we are testing for equality with this object. Returns:boolean `true` if obj is a FilePermission, and has the same pathname and actions as this FilePermission object, `false` otherwise. Annotations @Override

public boolean equals(Object obj)

Implements abstract java.security.Permission.equals.

Checks two FilePermission objects for equality. Checks that obj is a FilePermission, and has the same pathname and actions as this object.

Implementation Note

More specifically, two pathnames are the same if and only if they have the same wildcard flag and their cpath (if jdk.io.permissionsUseCanonicalPath is true) or npath (if jdk.io.permissionsUseCanonicalPath is false) are equal. Or they are both "<<ALL FILES>>".

When jdk.io.permissionsUseCanonicalPath is false, an invalid FilePermission does not equal to any object except for itself, even if they are created using the same invalid path.

Parameters

obj:Object: the object we are testing for equality with this object.

Returns:boolean

true if obj is a FilePermission, and has the same pathname and actions as this FilePermission object, false otherwise.

Annotations

@Override

getActions	back to summary
private static String getActions(int mask) Return the canonical string representation of the actions. Always returns present actions in the following order: read, write, execute, delete, readlink. Returns:String the canonical string representation of the actions.

getActions

back to summary

private static String getActions(int mask)

Return the canonical string representation of the actions. Always returns present actions in the following order: read, write, execute, delete, readlink.

Returns:String: the canonical string representation of the actions.

getActions back to summary

getActions	back to summary
public String getActions() Implements abstract java.security.Permission.getActions. Returns the "canonical string representation" of the actions. That is, this method always returns present actions in the following order: read, write, execute, delete, readlink. For example, if this FilePermission object allows both write and read actions, a call to `getActions` will return the string "read,write". Returns:String the canonical string representation of the actions. Annotations @Override

public String getActions()

Implements abstract java.security.Permission.getActions.

Returns the "canonical string representation" of the actions. That is, this method always returns present actions in the following order: read, write, execute, delete, readlink. For example, if this FilePermission object allows both write and read actions, a call to getActions will return the string "read,write".

Returns:String

the canonical string representation of the actions.

Annotations

@Override

getMask	back to summary
private static int getMask(String actions) Converts an actions String to an actions mask. Parameters actions:String the action string. Returns:int the actions mask.

getMask

back to summary

private static int getMask(String actions)

Converts an actions String to an actions mask.

Parameters

actions:String: the action string.

Returns:int

the actions mask.

getMask	back to summary
pack-priv int getMask() Return the current action mask. Used by the FilePermissionCollection. Returns:int the actions mask.

getMask

back to summary

pack-priv int getMask()

Return the current action mask. Used by the FilePermissionCollection.

Returns:int: the actions mask.

hashCode	back to summary
public int hashCode() Implements abstract java.security.Permission.hashCode. Returns the hash code value for this object. Returns:int a hash code value for this object. Annotations @Override

hashCode

back to summary

public int hashCode()

Implements abstract java.security.Permission.hashCode.

Returns the hash code value for this object.

Returns:int

a hash code value for this object.

Annotations

@Override

implies back to summary

implies	back to summary
public boolean implies(Permission p) Implements abstract java.security.Permission.implies. Checks if this FilePermission object "implies" the specified permission. More specifically, this method returns true if: p is an instanceof FilePermission, p's actions are a proper subset of this object's actions, and p's pathname is implied by this object's pathname. For example, "/tmp/" implies "/tmp/foo", since "/tmp/" encompasses all files in the "/tmp" directory, including the one named "foo". Precisely, a simple pathname implies another simple pathname if and only if they are equal. A simple pathname never implies a wildcard pathname. A wildcard pathname implies another wildcard pathname if and only if all simple pathnames implied by the latter are implied by the former. A wildcard pathname implies a simple pathname if and only if if the wildcard flag is "*", the simple pathname's path must be right inside the wildcard pathname's path. if the wildcard flag is "-", the simple pathname's path must be recursively inside the wildcard pathname's path. "<<ALL FILES>>" implies every other pathname. No pathname, except for "<<ALL FILES>>" itself, implies "<<ALL FILES>>". Implementation Note If `jdk.io.permissionsUseCanonicalPath` is `true`, a simple `cpath` is inside a wildcard `cpath` if and only if after removing the base name (the last name in the pathname's name sequence) from the former the remaining part is equal to the latter, a simple `cpath` is recursively inside a wildcard `cpath` if and only if the former starts with the latter. If `jdk.io.permissionsUseCanonicalPath` is `false`, a simple `npath` is inside a wildcard `npath` if and only if `simple_npath.relativize(wildcard_npath)` is exactly "..", a simple `npath` is recursively inside a wildcard `npath` if and only if `simple_npath.relativize(wildcard_npath)` is a series of one or more "..". This means "/-" implies "/foo" but not "foo". An invalid `FilePermission` does not imply any object except for itself. An invalid `FilePermission` is not implied by any object except for itself or a `FilePermission` on "<<ALL FILES>>" whose actions is a superset of this invalid `FilePermission`. Even if two `FilePermission` are created with the same invalid path, one does not imply the other. Parameters p:Permission the permission to check against. Returns:boolean `true` if the specified permission is not `null` and is implied by this object, `false` otherwise. Annotations @Override

public boolean implies(Permission p)

Implements abstract java.security.Permission.implies.

Checks if this FilePermission object "implies" the specified permission.

More specifically, this method returns true if:

p is an instanceof FilePermission,
p's actions are a proper subset of this object's actions, and
p's pathname is implied by this object's pathname. For example, "/tmp/*" implies "/tmp/foo", since "/tmp/*" encompasses all files in the "/tmp" directory, including the one named "foo".

Precisely, a simple pathname implies another simple pathname if and only if they are equal. A simple pathname never implies a wildcard pathname. A wildcard pathname implies another wildcard pathname if and only if all simple pathnames implied by the latter are implied by the former. A wildcard pathname implies a simple pathname if and only if

if the wildcard flag is "*", the simple pathname's path must be right inside the wildcard pathname's path.
if the wildcard flag is "-", the simple pathname's path must be recursively inside the wildcard pathname's path.

"<<ALL FILES>>" implies every other pathname. No pathname, except for "<<ALL FILES>>" itself, implies "<<ALL FILES>>".

Implementation Note

If jdk.io.permissionsUseCanonicalPath is true, a simple cpath is inside a wildcard cpath if and only if after removing the base name (the last name in the pathname's name sequence) from the former the remaining part is equal to the latter, a simple cpath is recursively inside a wildcard cpath if and only if the former starts with the latter.

If jdk.io.permissionsUseCanonicalPath is false, a simple npath is inside a wildcard npath if and only if simple_npath.relativize(wildcard_npath) is exactly "..", a simple npath is recursively inside a wildcard npath if and only if simple_npath.relativize(wildcard_npath) is a series of one or more "..". This means "/-" implies "/foo" but not "foo".

An invalid FilePermission does not imply any object except for itself. An invalid FilePermission is not implied by any object except for itself or a FilePermission on "<<ALL FILES>>" whose actions is a superset of this invalid FilePermission. Even if two FilePermission are created with the same invalid path, one does not imply the other.

Parameters

p:Permission: the permission to check against.

Returns:boolean

true if the specified permission is not null and is implied by this object, false otherwise.

Annotations

@Override

impliesIgnoreMask	back to summary
pack-priv boolean impliesIgnoreMask(FilePermission that) Checks if the Permission's actions are a proper subset of the this object's actions. Returns the effective mask iff the this FilePermission's path also implies that FilePermission's path. Parameters that:FilePermission the FilePermission to check against. Returns:boolean the effective mask

impliesIgnoreMask

back to summary

pack-priv boolean impliesIgnoreMask(FilePermission that)

Checks if the Permission's actions are a proper subset of the this object's actions. Returns the effective mask iff the this FilePermission's path also implies that FilePermission's path.

Parameters

that:FilePermission: the FilePermission to check against.

Returns:boolean

the effective mask

init	back to summary
private void init(int mask) initialize a FilePermission object. Common to all constructors. Also called during de-serialization. Parameters mask:int the actions mask to use. Annotations @SuppressWarnings:removal

init

back to summary

private void init(int mask)

initialize a FilePermission object. Common to all constructors. Also called during de-serialization.

Parameters

mask:int: the actions mask to use.

Annotations

@SuppressWarnings:removal

newPermissionCollection back to summary

newPermissionCollection	back to summary
public PermissionCollection newPermissionCollection() Overrides java.security.Permission.newPermissionCollection. Returns a new PermissionCollection object for storing FilePermission objects. FilePermission objects must be stored in a manner that allows them to be inserted into the collection in any order, but that also enables the PermissionCollection `implies` method to be implemented in an efficient (and consistent) manner. For example, if you have two FilePermissions: `"/tmp/-", "read"` `"/tmp/scratch/foo", "write"` and you are calling the `implies` method with the FilePermission: "/tmp/scratch/foo", "read,write", then the `implies` function must take into account both the "/tmp/-" and "/tmp/scratch/foo" permissions, so the effective permission is "read,write", and `implies` returns true. The "implies" semantics for FilePermissions are handled properly by the PermissionCollection object returned by this `newPermissionCollection` method. Returns:PermissionCollection a new PermissionCollection object suitable for storing FilePermissions. Annotations @Override

public PermissionCollection newPermissionCollection()

Overrides java.security.Permission.newPermissionCollection.

Returns a new PermissionCollection object for storing FilePermission objects.

FilePermission objects must be stored in a manner that allows them to be inserted into the collection in any order, but that also enables the PermissionCollection implies method to be implemented in an efficient (and consistent) manner.

For example, if you have two FilePermissions:

"/tmp/-", "read"
"/tmp/scratch/foo", "write"

and you are calling the implies method with the FilePermission:

    "/tmp/scratch/foo", "read,write",

then the implies function must take into account both the "/tmp/-" and "/tmp/scratch/foo" permissions, so the effective permission is "read,write", and implies returns true. The "implies" semantics for FilePermissions are handled properly by the PermissionCollection object returned by this newPermissionCollection method.

Returns:PermissionCollection

a new PermissionCollection object suitable for storing FilePermissions.

Annotations

@Override

readObject	back to summary
private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException readObject is called to restore the state of the FilePermission from a stream. Annotations @Serial

readObject

back to summary

private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException

readObject is called to restore the state of the FilePermission from a stream.

Annotations

@Serial

withNewActions	back to summary
pack-priv FilePermission withNewActions(int effective) Create a cloned FilePermission with a different actions. Parameters effective:int the new actions Returns:FilePermission a new object

withNewActions

back to summary

pack-priv FilePermission withNewActions(int effective)

Create a cloned FilePermission with a different actions.

Parameters

effective:int: the new actions

Returns:FilePermission

a new object

writeObject	back to summary
private void writeObject(ObjectOutputStream s) throws IOException WriteObject is called to save the state of the FilePermission to a stream. The actions are serialized, and the superclass takes care of the name. Annotations @Serial

writeObject

back to summary

private void writeObject(ObjectOutputStream s) throws IOException

WriteObject is called to save the state of the FilePermission to a stream. The actions are serialized, and the superclass takes care of the name.

Annotations

@Serial

public final Class FilePermission

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail