imageorg
Interface FileElement

All Superinterfaces:

java.io.Serializable

All Known Subinterfaces:

Folder, Image

public interface FileElement
extends java.io.Serializable

FileElement is the super-interface for all disk-based Image Organizer files. The methods in this interface define a common protocol for the subtypes (Folder and Image). It is envisaged that you would create an abstract class (e.g. MyFunkyFileElement) that implements this interface and provides as much general purpose, reusable code as possible. Your subtypes (e.g. MyFunkyFolder and MyFunkyImage) would extend MyFunkyFileElement and implement its abstract methods (if any) and the sub interfaces (Folder and Image).

See Also:

Serializable

Method Summary

boolean	addAnnotation(Annotation toAdd) Associate the supplied Annotation with this FileElement.
boolean	copy(Folder destination) Copies this file element to the supplied destination Folder.
boolean	delete() Removes this FileElement from any internal data structure and deletes its corresponding disk file.
java.util.Collection<Annotation>	getAnnotations() Return a Collection of the Annotations associated with this FileElement.
java.lang.String	getName() Returns the name of this FileElement.
boolean	move(Folder destination) Moves this FileElement to the supplied destination Folder.
boolean	removeAnnotation(Annotation toRemove) Removes the supplied Annotation from this FileElement.
boolean	rename(java.lang.String newName) Renames this FileElement to the the supplied newName.

Method Detail

getName

java.lang.String getName()

Returns the name of this FileElement. Note that a FileElement's name is just its name and does not include the path to the file on disk. E.g. if this FileElement represents the disk file /home/mhall/image_org_home/sunset.jpg, then the name returned by this method is sunset.jpg.

Returns:

the name of this FileElement

rename

boolean rename(java.lang.String newName)
               throws java.lang.Exception

Renames this FileElement to the the supplied newName. Note that this method should just change the name (as returned by getName() of the FileElement. E.g. if this file element represents the disk file /home/mhall/image_org_home/sunset.jpg, then the call rename("beach.jpg") would result in getName() returning the String "beach.jpg" and the disk file becoming /home/mhall/image_org_home/beach.jpg.

Parameters:

newName - the new name of this FileElement.
(Precondition: newName != null)

Returns:

true if the rename operation was successful.

Throws:

java.lang.Exception - if something goes wrong during renaming

delete

boolean delete()
               throws java.lang.Exception

Removes this FileElement from any internal data structure and deletes its corresponding disk file.

Returns:

a boolean value

Throws:

java.lang.Exception - if an error occurs during deletion.

move

boolean move(Folder destination)
             throws java.lang.Exception

Moves this FileElement to the supplied destination Folder. E.g. if this FileElement represents the disk folder /home/mhall/image_org_home/fast_cars and the destination Folder represents the disk folder /home/mhall/image_org_home/cars, then this method would result in /home/mhall/image_org_home/cars/fast_cars being created and /home/mhall/image_org_home/cars ceasing to exist.

Note that most of the code for this method should be equally applicable to both Folder's and Image's.

This method should check for and return false for the following cases:

1. This FileElement doesn't exist (i.e. the file it represents doesn't exist on disk.

2. This FileElement is the home directory (image_org_home).

3. The destination Folder doesn't exist.

4. The destination Folder is the same as this FileElement.

5. This FileElement is a Folder and The destination Folder is the immediate parent of this Folder.

Parameters:

destination - the destination Folder to move to.
(Precondition: destination != null)

Returns:

true if the move operation succeeds.

Throws:

java.lang.Exception - if something goes wrong during the move.

copy

boolean copy(Folder destination)
             throws java.lang.Exception

Copies this file element to the supplied destination Folder. Is similar to move() (see docs for move()) except that the original FileElement is left in place (on disk as well as in any memory-based data structure) and a copy is made in the destination Folder.

Note that this method will require specific implementations in the Folder and Image subtypes. Folders will need to copy their contents recursively. Copying Folders and Images will require the use of binary I/O - see java.io.InputStream and java.io.OutputStream.

This method should check (and return false) for the same special cases that move() does.

Parameters:

destination - the destination Folder to copy to.
(Precondition: destination != null)

Returns:

true if the copy operation succeeds

Throws:

java.lang.Exception - if something goes wrong during the copy.

addAnnotation

boolean addAnnotation(Annotation toAdd)

Associate the supplied Annotation with this FileElement.

Parameters:

toAdd - the Annotation object to add.
(Precondition: toAdd != null)

Returns:

true if the add operation succeeds. False is returned if (based on the annotation key) the supplied Annotation has already been associated with this FileElement.

removeAnnotation

boolean removeAnnotation(Annotation toRemove)

Removes the supplied Annotation from this FileElement.

Parameters:

toRemove - Annotation object to remove.
(Precondition: toRemove != null)

Returns:

true if the operation succeeds. False is returned if (based on the annotation key) the supplied Annotation is not associated with this FileElement.

getAnnotations

java.util.Collection<Annotation> getAnnotations()

Return a Collection of the Annotations associated with this FileElement.

Returns:

this FileElement's Annotations.