imageorg
Class ImageOrganizer

java.lang.Object
  imageorg.ImageOrganizer

public abstract class ImageOrganizer
extends java.lang.Object

ImageOrganizer is the main interface to the image organization library. It is used to obtain and manipulate FileElements that represent disk-based folders and images. ImageOrganizer is an abstract class that declares various abstract methods that a concrete implementation should provide. You should subclass ImageOrganizer and provide your own implementation for the abstract methods. IMPORTANT: There is one method that you need to provide an implementation for in this class. The static factory method create() should return an object which is your concrete subclass of ImageOrganizer. This is the only case where you will have to directly change code in the imageorg package.

ImageOrganizer provides a single protected constant REPOSITORY_HOME defining the on disk root (or home) directory that will contain all images and folders maintained by the ImageOrganizer library. The getHome() method will return a concrete implementation of the Folder interface that encapsulates the home directory.

Users of the ImageOrganizer library will maniplulate images and folders using methods defined in the FileElement, Folder and Image interfaces.

Field Summary

protected static java.io.File

REPOSITORY_HOME Constant that defines the platform independent on disk path to the ImageOrganizer home directory.

Constructor Summary

ImageOrganizer()

Method Summary

static ImageOrganizer	create() Factory method that returns a concrete subclass of ImageOrganizer.
abstract Annotation	createAnnotation(java.lang.String annotationKey) This method is a factory method that will return a concrete implementation of the Annotation interface.
abstract Folder	getHome() Returns a concrete implementation of the Folder interface that encapsulates the home (or root) directory of the ImageOrganizer file hierarchy.
abstract boolean	importFrom(java.io.File source, Folder destination) Imports image(s) from the supplied source File to the supplied destination Folder.
abstract void	save() Save any internal data structures to disk.
abstract java.util.Collection<FileElement>	search(java.lang.String searchText, Folder root) Searches for occurrences of the substring searchText in FileElements contained in the Folder root ( including root itself).

Methods inherited from class java.lang.Object

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

Field Detail

REPOSITORY_HOME

protected static final java.io.File REPOSITORY_HOME

Constant that defines the platform independent on disk path to the ImageOrganizer home directory.

Constructor Detail

ImageOrganizer

public ImageOrganizer()

Method Detail

create

public static ImageOrganizer create()

Factory method that returns a concrete subclass of ImageOrganizer. Fill in code here to return an object that provides implementations of the abstract methods in this class.

Eg. return new implementation.MyFunkyImageOrganizer();

Returns:

an object that is a concrete subclass of ImageOrganizer

getHome

public abstract Folder getHome()
                        throws java.lang.Exception

Returns a concrete implementation of the Folder interface that encapsulates the home (or root) directory of the ImageOrganizer file hierarchy. The on disk home directory is defined by the constant REPOSITORY_HOME above.

This method must be robust. That is, if the home directory does not exist the method should create it on disk and then return a Folder encapsulating it.

Returns:

the Folder representing the root of the ImageOrganizer file hierarchy.

Throws:

java.lang.Exception - if the home Folder can't be obtained.

importFrom

public abstract boolean importFrom(java.io.File source,
                                   Folder destination)
                            throws java.lang.Exception

Imports image(s) from the supplied source File to the supplied destination Folder. source images are copied to the destination. If the source File is a directory, then the contents of the directory are to be copied to the destination Folder preserving the original hierarchical structure.

E.g. If the source looks like:

 
 /home/mhall/marksImages/
                       | 
                       |-- landscape1.jpg 
                       |-- beach.gif 
                       |-- Cars/ 
                              | 
                              |-- astonMartin.gif 
 


 Then a call to importFrom where 
 source = /home/mhall/marksImages and 
 destination = getHome() would result in:



 
 
 /home/mhall/image_org_home/ 
                          | 
                          |-- marksImages/ 
                                        | 
                                        |-- landscape.jpg 
                                        |-- beach.gif 
                                        |-- Cars/ 
                                               | 
                                               |-- astonMartin.gif 
 

IMPORTANT: This method should not import anything that is not an image (gif or jpeg) or folder. You can make use of a static utility function called loadImage() in the imageviewer.ImageViewer class to load images. This method returns null if a file can't be decoded as an image (gif or jpeg).

(Postcondition: contents of source are copied to destination)

Parameters:

source - the file or directory to import.
(Precondition: source != null)

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

Returns:

true if the import was successfull

Throws:

java.lang.Exception - if an error occurs during the import.

search

public abstract java.util.Collection<FileElement> search(java.lang.String searchText,
                                                         Folder root)

Searches for occurrences of the substring searchText in FileElements contained in the Folder root ( including root itself). FileElements that are sub-folders should have their contents searched in a recursive fashion. Names (as returned by a call to getName() on a FileElement) as well as any Annotations (annotation keys and values) are to be checked for occurrences of the searchText. A Collection of FileElements that match are to be returned. The returned Collection must be non-null and can be empty (i.e. size 0) to indicate that no matches were found.

(Postcondition: a non-null (but possibly empty) Collection of matching FileElements is returned)

Parameters:

searchText - the substring to search for.
(Precondition: searchText != null)

root - the Folder at which to begin searching (this folder itself is also checked to see if it is a match).
(Precondition: root != null)

Returns:

a Collection of FileElements that match the search criteria

save

public abstract void save()
                   throws java.lang.Exception

Save any internal data structures to disk. Object serialization is the easiest option to use for saving the state of the ImageOrganizer's file hierarchy. Serialized data structures should not be saved into the ImageOrganizer's home directory (REPOSITORY_HOME), instead they should be saved to a single file called .imageorg in the User's "home" directory. A call to System.getProperties().getProperty("user.home") can be used to obtain the path to the User's "home" directory in a platform independent manner.

Maintaining an internal representation of the on disk folder hierarchy is necessary for associating Annotations with individual FileElements. Since the ImageOrganizer's on disk folder hierarchy should contain only directories and images, you shouldn't save annotation data to separate individual files in the on-disk folder hierarchy.

You can assume that clients will call this save() method after they are finished using the ImageOrganizer library.

Throws:

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

createAnnotation

public abstract Annotation createAnnotation(java.lang.String annotationKey)

This method is a factory method that will return a concrete implementation of the Annotation interface. Its operation is similar to that of the create() method above. The primary difference is that this method is non-static, which means that the implementation will go in your concrete sub-class of ImageOrganizer.

Parameters:

annotationKey - the key value to use when creating a new
(Precondition: annotationKey != null). Annotation (see docs for the Annotation interface.

Returns:

an object that implements the Annotation interface.