org.torweg.pulse.vfs
Class VirtualFile

java.lang.Object
  org.torweg.pulse.util.entity.AbstractBasicEntity
      org.torweg.pulse.util.entity.AbstractNamedEntity
          org.torweg.pulse.vfs.VirtualFile

All Implemented Interfaces:

java.io.Serializable, JDOMable, INamed

@Entity
public class VirtualFile
extends AbstractNamedEntity
implements INamed, JDOMable

a file in the VirtualFileSystem.

The maximum length for a URI denoting a VirtualFile is 131072 bytes: This allows a path depth of 255 with a maximum file name length of 256 characters each, stored in UTF-8.

Due to various compatibility issues a VirtualFile's name must match the following regular expression: [a-zA-Z0-9_\.\- ]+.

URIs to VirtualFiles are constructed as follows:

• <em>scheme</em>: [public | private]
• <em>authority</em>: none

Examples:

• private:///mydirectory/myfile.txt
• public:///fileInRootDirectory.xml
• public:///file/In/DirectoryDescriptor/Structure/photo.png

To get an instance of a VirtualFile use VirtualFileSystem.getVirtualFile(URI, User) or VirtualFileSystem.getVirtualFile(String, User).

Version:

$Revision: 2067 $

Author:

Thomas Weber, Daniel Dietz

See Also:

Serialized Form

Field Summary

static java.lang.String

VALID_NAME_REGEX regular expression to determine if a name is valid for a VirtualFile.

Constructor Summary

protected	VirtualFile() Deprecated.
protected	VirtualFile(User acc, java.net.URI p) constructs a new VirtualFile for the given URI with the given User as the accessor.

Method Summary

boolean	addDeadProperty(DeadProperty prop) adds the given dead property to the file's dead properties.
void	addReadRole(Role r) adds a Role to the read roles.
void	addWriteRole(Role r) adds a Role to the write roles.
boolean	canRead(User u) tests whether the given User is allowed to read the VirtualFile.
boolean	canWrite(User u) tests whether the given User is allowed to write to the VirtualFile.
protected static java.net.URI	cleanURI(java.net.URI uri) cleans a VFS URI.
void	clearReadRoles() Clears the read-roles.
void	clearWriteRoles() Clears the write-roles.
long	created() convenience method for getCreated() to resemble java.io.File.
org.jdom.Element	deserializeToJDOM() this will deserialize the state of the JDOMable as a JDOM Element.
boolean	equals(java.lang.Object o) compares the VirtualFile to the given Object.
boolean	exists() tests whether the file or directory denoted by this abstract pathname exists.
java.util.List<VirtualFile>	getChildren() returns the children of the VirtualFile, if it is a directory.
long	getCreated() returns the timestamp of the creation of the VirtualFile.
User	getCreator() returns the User who created the VirtualFile.
java.util.Set<DeadProperty>	getDeadProperties() returns an unmodifiable view of the dead properties.
DeadProperty	getDeadProperty(DeadProperty prototype) returns the file's DeadProperty identified by the given prototype.
java.lang.String	getETag() returns a strong ETag for the VirtualFile (see RFC 2616, Section 14.19).
java.lang.Long	getFilesize() returns the size of the VirtualFile in bytes or -1, if the VirtualFile is a directory.
java.net.URI	getHttpURI() returns a URI to access the VirtualFile via HTTP.
long	getLastModified() returns the timestamp of the last modification.
User	getLastModifier() returns the User who modified the VirtualFile most recently.
VirtualFile	getParent() returns the parent VirtualFile or null, if this VirtualFile is in the root of a store.
java.util.Set<Role>	getReadRoles() returns an unmodifiable view of the read roles.
java.net.URI	getURI() returns the path denoting the VirtualFile.
java.util.Set<Role>	getWriteRoles() returns an unmodifiable view of the write roles.
int	hashCode() returns a hash code for the VirtualFile.
boolean	isDirectory() returns true, if the VirtualFile is a directory.
boolean	isFile() returns true, if the VirtualFile is a file.
boolean	isPublic() indicates, whether the VirtualFile is from the public or the private store.
long	lastModified() convenience method for getLastModified() to resemble java.io.File.
protected void	removeChild(VirtualFile f) removes a child from the parent.
boolean	removeDeadProperty(DeadProperty prototype) removes a given dead property from the file's dead properties.
void	removeReadRole(Role r) removes a Role from the read roles.
void	removeWriteRole(Role r) removes a Role from the write roles.
protected void	setDirectory(boolean isDir) VFS internally used method to set the isDirectory flag.
protected void	setFilesize(java.lang.Long size) sets the filesize.
protected void	setLastModified(java.lang.Long lm) sets the timestamp of the last modification.
protected void	setLastModifier(User user) sets the User who modified the VirtualFile most recently.
protected void	setParent(VirtualFile p) this method should be called from the constructors of implementing classes to store a reference to the parent VirtualFile.
protected void	setParent(VirtualFile p, boolean inheritPermissions) this method should be called from the constructors of implementing classes to store a reference to the parent VirtualFile.
protected void	setURI(java.net.URI p) sets the path for the VirtualFile.
net.sf.json.JSONObject	toJSON() returns a JSON-representation of the VirtualFile.

Methods inherited from class org.torweg.pulse.util.entity.AbstractNamedEntity

getName, setName

Methods inherited from class org.torweg.pulse.util.entity.AbstractBasicEntity

compareTo, getFullQualifiedClassNameJAXB, getId

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.torweg.pulse.util.INamed

getName

Field Detail

VALID_NAME_REGEX

public static final java.lang.String VALID_NAME_REGEX

regular expression to determine if a name is valid for a VirtualFile.

See Also:

Constant Field Values

Constructor Detail

VirtualFile

@Deprecated
protected VirtualFile()

Deprecated.

protected constructor for Hibernate^TM.

NOTE: To get an instance of a VirtualFile use VirtualFileSystem.getVirtualFile(URI, User) or VirtualFileSystem.getVirtualFile(String, User) .

VirtualFile

protected VirtualFile(User acc,
                      java.net.URI p)
               throws VFIOException

constructs a new VirtualFile for the given URI with the given User as the accessor.

NOTE: To get an instance of a VirtualFile use VirtualFileSystem.getVirtualFile(URI, User) or VirtualFileSystem.getVirtualFile(String, User) .

Parameters:

acc - the User to be used for access checks

p - the URI of the file

Throws:

VFIOException - if the given URI is not a legal URI for VirtualFiles

Method Detail

cleanURI

protected static java.net.URI cleanURI(java.net.URI uri)
                                throws VFIOException,
                                       java.net.URISyntaxException

cleans a VFS URI.

Parameters:

uri - the URI to clean

Returns:

the cleaned URI

Throws:

VFIOException - on errors checking the URI

java.net.URISyntaxException - on errors creating the cleaned URI

setDirectory

protected final void setDirectory(boolean isDir)

VFS internally used method to set the isDirectory flag.

Parameters:

isDir - true for directories; otherwise false

created

public final long created()

convenience method for getCreated() to resemble java.io.File.

Returns:

the timestamp of the creation of the VirtualFile

See Also:

getCreated()

getCreated

public final long getCreated()

returns the timestamp of the creation of the VirtualFile.

Returns:

the timestamp of the creation of the VirtualFile

getCreator

public final User getCreator()

returns the User who created the VirtualFile.

Returns:

the User who created the VirtualFile

lastModified

public final long lastModified()

convenience method for getLastModified() to resemble java.io.File.

Returns:

the timestamp of the last modification of the VirtualFile

See Also:

getLastModified()

getLastModified

public final long getLastModified()

returns the timestamp of the last modification.

Returns:

the timestamp of the last modification

setLastModified

protected final void setLastModified(java.lang.Long lm)

sets the timestamp of the last modification.

Parameters:

lm - the timestamp

getLastModifier

public final User getLastModifier()

returns the User who modified the VirtualFile most recently.

Returns:

the User who modified the VirtualFile most recently

setLastModifier

protected final void setLastModifier(User user)

sets the User who modified the VirtualFile most recently.

Parameters:

user - the last modifier of the file

getFilesize

public final java.lang.Long getFilesize()

returns the size of the VirtualFile in bytes or -1, if the VirtualFile is a directory.

Returns:

the size of the VirtualFile in bytes or -1, if the VirtualFile is a directory

setFilesize

protected final void setFilesize(java.lang.Long size)

sets the filesize.

Parameters:

size - the filesize in bytes.

getDeadProperties

public final java.util.Set<DeadProperty> getDeadProperties()

returns an unmodifiable view of the dead properties.

Returns:

an unmodifiable view of the dead properties

addDeadProperty

public final boolean addDeadProperty(DeadProperty prop)
                              throws VFIOException

adds the given dead property to the file's dead properties.

If the file already contains a dead property which is equal to the given property (DeadProperty.equals(Object)), the existing property is patched (DeadProperty.patch(DeadProperty)) with the given property.

Parameters:

prop - the property to be added

Returns:

true, if and only if, the property has been added. Otherwise false.

Throws:

VFIOException - on errors patching an existing property

getDeadProperty

public final DeadProperty getDeadProperty(DeadProperty prototype)

returns the file's DeadProperty identified by the given prototype.

Parameters:

prototype - the prototype of the requested property

Returns:

the file's DeadProperty identified by the given prototype or null, if no such property exists

See Also:

DeadProperty.extractPrototype()

removeDeadProperty

public final boolean removeDeadProperty(DeadProperty prototype)

removes a given dead property from the file's dead properties.

Parameters:

prototype - the property to remove

Returns:

true, if and only if, the property has been removed. Otherwise false.

getURI

public final java.net.URI getURI()

returns the path denoting the VirtualFile.

Returns:

the path denoting the VirtualFile

setURI

protected final void setURI(java.net.URI p)
                     throws java.io.UnsupportedEncodingException, IllegalFileNameException

sets the path for the VirtualFile.

Parameters:

p - the path

Throws:

java.io.UnsupportedEncodingException - on errors decoding the name from the path

IllegalFileNameException - if the name of the VirtualFile does not match [a-zA-Z0-9_\.\-]+.

getHttpURI

public final java.net.URI getHttpURI()

returns a URI to access the VirtualFile via HTTP.

Returns:

a URI to access the VirtualFile via HTTP, or null if the VirtualFile is private

isDirectory

public final boolean isDirectory()

returns true, if the VirtualFile is a directory.

Returns:

true, if the VirtualFile is a directory. Otherwise false.

See Also:

isFile()

isFile

public final boolean isFile()

returns true, if the VirtualFile is a file.

Returns:

true, if the VirtualFile is a file. Otherwise false.

See Also:

isDirectory()

canRead

public final boolean canRead(User u)

tests whether the given User is allowed to read the VirtualFile.

Parameters:

u - the user to check against

Returns:

true if and only if the file specified by this abstract pathname exists and can be read by the user; false otherwise

canWrite

public final boolean canWrite(User u)

tests whether the given User is allowed to write to the VirtualFile.

Parameters:

u - the user to check against

Returns:

true if and only if the file specified by this abstract pathname exists and can be written by the user; false otherwise

addReadRole

public final void addReadRole(Role r)

adds a Role to the read roles.

Parameters:

r - the role to add

removeReadRole

public final void removeReadRole(Role r)

removes a Role from the read roles.

Parameters:

r - the role to remove

getReadRoles

public final java.util.Set<Role> getReadRoles()

returns an unmodifiable view of the read roles.

Returns:

an unmodifiable view of the read roles

clearReadRoles

public final void clearReadRoles()

Clears the read-roles.

addWriteRole

public final void addWriteRole(Role r)

adds a Role to the write roles.

Parameters:

r - the role to add

removeWriteRole

public final void removeWriteRole(Role r)

removes a Role from the write roles.

Parameters:

r - the role to remove

clearWriteRoles

public final void clearWriteRoles()

Clears the write-roles.

getWriteRoles

public final java.util.Set<Role> getWriteRoles()

returns an unmodifiable view of the write roles.

Returns:

an unmodifiable view of the write roles

exists

public final boolean exists()

tests whether the file or directory denoted by this abstract pathname exists.

Returns:

true if and only if the file or directory denoted by this abstract pathname exists; false otherwise

getETag

public final java.lang.String getETag()

returns a strong ETag for the VirtualFile (see RFC 2616, Section 14.19).

Returns:

a strong ETag

getParent

public final VirtualFile getParent()

returns the parent VirtualFile or null, if this VirtualFile is in the root of a store.

Returns:

the parent VirtualFile or null, if this VirtualFile is in the root of a store

setParent

protected final void setParent(VirtualFile p)

this method should be called from the constructors of implementing classes to store a reference to the parent VirtualFile.

Overriding methods must ensure to call super.setParent(VirtualFile)!

Parameters:

p - the parent VirtualFile

setParent

protected final void setParent(VirtualFile p,
                               boolean inheritPermissions)

this method should be called from the constructors of implementing classes to store a reference to the parent VirtualFile.

Overriding methods must ensure to call super.setParent(VirtualFile, boolean)!

Parameters:

p - the parent VirtualFile

inheritPermissions - true, if all Permissions of the parent shall be inherited.

removeChild

protected final void removeChild(VirtualFile f)

removes a child from the parent.

Parameters:

f - the child to be removed

getChildren

public final java.util.List<VirtualFile> getChildren()
                                              throws VFIOException

returns the children of the VirtualFile, if it is a directory.

Returns:

the children of the VirtualFile, if it is a directory

Throws:

VFIOException - if the VirtualFile is not a directory

isPublic

public final boolean isPublic()

indicates, whether the VirtualFile is from the public or the private store.

Returns:

true, if the VirtualFile is from the public store. Otherwise false.

deserializeToJDOM

public org.jdom.Element deserializeToJDOM()

Description copied from interface: JDOMable

this will deserialize the state of the JDOMable as a JDOM Element.

Specified by:

deserializeToJDOM in interface JDOMable

Returns:

an XML representation of the VirtualFile

hashCode

public int hashCode()

returns a hash code for the VirtualFile.

Overrides:

hashCode in class AbstractBasicEntity

Returns:

a hash code for the VirtualFile

See Also:

AbstractBasicEntity.hashCode()

equals

public boolean equals(java.lang.Object o)

compares the VirtualFile to the given Object.

Overrides:

equals in class AbstractBasicEntity

Parameters:

o - the Object to compare to

Returns:

true, if and only if the given Object is a VirtualFile with the same URI

toJSON

public final net.sf.json.JSONObject toJSON()

returns a JSON-representation of the VirtualFile.

Returns:

a JSON-representation of the VirtualFile