net.jqhome.jwps.ea
Class FileEAs

java.lang.Object
  |
  +--net.jqhome.jwps.JWPLoader
        |
        +--net.jqhome.jwps.ea.FileEAs

public class FileEAs

extends JWPLoader

This class represents the extended attributes (EAs) on a file running under OS/2 2.0 or above.

Lifecycle

Instantiate this class as needed. There is no special shutdown required when you are done with it.

Usage

This is used when you need to access the EAs for a file system object (file or folder).

An extended attribute is a bit of that is part of a file and is kept with the file by the operating system. This means that these are preserved when copying or moving a file. Java is normally completely unaware of these and therefore these get sometimes lost whenever a file is manipulated in Java. This class is the answer to that.

EAs normally require a lot of really nasty programming in C, since they are kept in a format that warms any assembly language programmer's heart.There are many places to go wrong in using EAs natively. All of this has been removed and it is hoped that you will find them easy enough to use that they will become a standard part of your programming vocabulary.

The default for setting EAs is to not set those that have been flagged as bad. This helps prevent changing the EAs of some other application, which does not know how to write them properly. Again, good citizenship means leave other folks EAs alone if possible.

Field Summary

static int

MAX_EA_SIZE The maximum size of an EA, 64kbytes.

Constructor Summary

FileEAs(java.io.File file)
Constructor for this class.

FileEAs(java.lang.String fileName)
Constructor for this class.

Method Summary

protected EAHashtable	_getAllEAs(java.lang.String fileName)
protected int	_getEASize(java.lang.String fileName)
protected net.jqhome.tools.StringVector	_listEANames(java.lang.String fileName)
protected void	_removeEA(java.lang.String fileName, java.lang.String eaName)
protected void	_setEA(java.lang.String fileName, RawEA rawEA)
EAHashtable	getAllEAs()
AbstractEA	getEA(AbstractEA aEA) Convenience for getting an EA.
AbstractEA	getEA(java.lang.String eaName)
int	getEASize() Returns the amount of space taken up on disk by the EAs.
java.lang.String	getFileName() Retrieves the file name for this class.
net.jqhome.tools.StringVector	listEANames() Lists all of the EA names associated with this file.
void	removeAllEAs()
void	removeEA(AbstractEA aEA) Removes a single EA, given the EA.
void	removeEA(java.lang.String eaName) Removes a single EA, given its name.
void	removeEAs(AbstractEA[] aEAs) Removes a list of EAs, passed as an array of AbstractEA objects.
void	removeEAs(EAHashtable eaHT) Removes all the EAs that occur in the given EA hashtable from the file.
void	removeEAs(java.util.Vector v) Removes a list of EAs, passed as a java.util.Vector objects.
void	setEA(AbstractEA ea)
void	setEAs(AbstractEA[] aEAs) This will not set bad EAs.
void	setEAs(AbstractEA[] aEAs, boolean setBadEAs) Sets a list of EAs, given as an array of AbstractEA objects.
void	setEAs(EAHashtable eaHT) Default is to not set bad EAs
void	setEAs(EAHashtable eaHT, boolean setBadEAs) Sets the EAs from the hashtable.
void	setEAs(java.util.Vector v) Default is to not set bad EAs
void	setEAs(java.util.Vector v, boolean setBadEAs) Sets a list of EAs, given as a java.util.Vector.

Methods inherited from class java.lang.Object

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

Field Detail

MAX_EA_SIZE

public static int MAX_EA_SIZE

The maximum size of an EA, 64kbytes. This is a limit imposed by OS/2.

Constructor Detail

FileEAs

public FileEAs(java.lang.String fileName)
        throws JWPException

Constructor for this class. The file or directory must exist.

FileEAs

public FileEAs(java.io.File file)
        throws JWPException

Constructor for this class. The file or directory must exist.

Method Detail

getFileName

public java.lang.String getFileName()

Retrieves the file name for this class.

setEA

public void setEA(AbstractEA ea)
           throws JWPException

JWPException

_setEA

protected void _setEA(java.lang.String fileName,
                      RawEA rawEA)
               throws JWPException

JWPException

_listEANames

protected net.jqhome.tools.StringVector _listEANames(java.lang.String fileName)
                                              throws JWPException

JWPException

listEANames

public net.jqhome.tools.StringVector listEANames()
                                          throws JWPException

Lists all of the EA names associated with this file.

JWPException

getEA

public AbstractEA getEA(java.lang.String eaName)
                 throws JWPException

JWPException

getEA

public AbstractEA getEA(AbstractEA aEA)
                 throws JWPException

Convenience for getting an EA.

JWPException

getAllEAs

public EAHashtable getAllEAs()
                      throws JWPException

JWPException

_getAllEAs

protected EAHashtable _getAllEAs(java.lang.String fileName)
                          throws JWPException

JWPException

setEAs

public void setEAs(java.util.Vector v)
            throws JWPException

Default is to not set bad EAs

JWPException

setEAs

public void setEAs(java.util.Vector v,
                   boolean setBadEAs)
            throws JWPException

Sets a list of EAs, given as a java.util.Vector. See note on speed in the array version of this call.

JWPException

setEAs

public void setEAs(EAHashtable eaHT)
            throws JWPException

Default is to not set bad EAs

JWPException

setEAs

public void setEAs(EAHashtable eaHT,
                   boolean setBadEAs)
            throws JWPException

Sets the EAs from the hashtable. See note on speed in the array version fo this call.

JWPException

setEAs

public void setEAs(AbstractEA[] aEAs)
            throws JWPException

This will not set bad EAs. You must call the version of this that has a boolean.

JWPException

setEAs

public void setEAs(AbstractEA[] aEAs,
                   boolean setBadEAs)
            throws JWPException

Sets a list of EAs, given as an array of AbstractEA objects. If you have several EAs to write to disk, it is best to use this call since otherwise each setEA call causes the entire set of EAs to be checked for size. This is done once in this call, making it run much (as in 10x) faster.

This will only overrite EAs flagged as bad if you tell it to. The assumption is that if an EA is corrupt, this is because some other application wrote something very specific and fiddling with these is bad form.

JWPException

removeEAs

public void removeEAs(AbstractEA[] aEAs)
               throws JWPException

Removes a list of EAs, passed as an array of AbstractEA objects. Note: it has been found for very large numbers of these (in the hundreds) that this can simply fail. If you need that many EAs, it is probably a good idea to put them into a single multi-valued EA.

JWPException

removeEAs

public void removeEAs(java.util.Vector v)
               throws JWPException

Removes a list of EAs, passed as a java.util.Vector objects. See note in array-valued method.

JWPException

removeEAs

public void removeEAs(EAHashtable eaHT)
               throws JWPException

Removes all the EAs that occur in the given EA hashtable from the file.

JWPException

removeAllEAs

public void removeAllEAs()
                  throws JWPException

JWPException

removeEA

public void removeEA(AbstractEA aEA)
              throws JWPException

Removes a single EA, given the EA.

JWPException

_removeEA

protected void _removeEA(java.lang.String fileName,
                         java.lang.String eaName)
                  throws JWPException

JWPException

removeEA

public void removeEA(java.lang.String eaName)
              throws JWPException

Removes a single EA, given its name.

JWPException

_getEASize

protected int _getEASize(java.lang.String fileName)
                  throws JWPException

JWPException

getEASize

public int getEASize()
              throws JWPException

Returns the amount of space taken up on disk by the EAs. This is larger than simply the data and the name, since other control information has to be saved too. This is used to determine if there is enough space to write an EA. One of the more charming aspects of the underlying C API is that there is no checking of any sort done before writing an EA. If you exceed the 64k limit, it will be written and the system will be unable to read it, resulting in corrupted and unusable EAs. In line with our design philosophy, any and all checking is done for you, so you don't normally have to check this value yourself.

JWPException