ccs.utils
Class SortingFolderEntry

java.lang.Object
  ccs.utils.SortingFolderEntry

public class SortingFolderEntry
extends java.lang.Object

This class assists the rather common pattern whereby there is a "folder" full of filenames, some of which are subfolders, and which must be sorted. This occurs in various guises in pretty much every Checkpoint product there is; historically, all of these have used custom code to address the problem since each case encounters it in a slightly different guise.

This class attempts to common up the directory-sorting section of the problem, while allowing enough flexibility not to break the existing code (which handles the large areas of difference involved).

On notation: pretty much everywhere else, the pattern here called a "folder" is called a "directory", which is the historical term. However, it seems possible that in the not too distant future we'll be wanting to reserve "directory" for the LDAP sense; this is the vanguard of a long and slow terminology migration.

Constructor Summary

SortingFolderEntry(java.lang.String rawname, java.lang.Object maino, boolean isFolder, boolean isAcceptable)
Create a new SortingFolderEntry.

Method Summary

java.lang.String	getExtn()
java.lang.String	getName()
java.lang.String	getQuery()
boolean	isAcceptable()
boolean	isFolder()
static SortingFolderEntry[]	listFiles(java.io.File folderf, java.io.FileFilter filter) A helper method for the common special case where you need to generate a directory listing for a disk directory.
java.lang.Object	mainObject()
static int	search(SortingFolderEntry[] contents, SortingFolderEntry key) Find the index of the specified entry in the supplied array.
static void	sort(SortingFolderEntry[] contents) Sort this array of folder entries into their proper order.
java.lang.String	toEncoded()
void	xmlMarshal(java.io.PrintWriter pw) Marshal the entry as XML.
void	xmlMarshal(java.io.PrintWriter pw, boolean foldersOnly) Marshal the entry as XML.
static void	xmlMarshalFolder(java.io.PrintWriter pw, SortingFolderEntry[] sfes, java.io.File folderf, java.lang.String filterPattern, boolean foldersOnly) A helper method to marshal the current folder as XML, in the common special case where the folder is a disk file.
static void	xmlMarshalFolder(java.io.PrintWriter pw, SortingFolderEntry[] sfes, java.lang.String folderPath, char separator, java.lang.String filterPattern, boolean includeUp, boolean foldersOnly) A helper method to marshal the current folder as XML.

Methods inherited from class java.lang.Object

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

Constructor Detail

SortingFolderEntry

public SortingFolderEntry(java.lang.String rawname,
                          java.lang.Object maino,
                          boolean isFolder,
                          boolean isAcceptable)

Create a new SortingFolderEntry.

Parameters:

rawname - The name portion of the contents' path. This should not contain any path separators.

maino - The "main object" for which this contains denormalised sorting information. In general, SortingFolderEntry arrays are used to display a "folder listing" for the user; when the user then picks an entry, the app will need to retrieve maino in order to do whatever the user asked for.

isFolder - whether the entry is a subfolder.

isAcceptable - Whether the file meets your filtering requirements. If you have no filter, set this to true. Directories should always be acceptable.

Method Detail

getName

public java.lang.String getName()

Returns:

The name of the file, without any extension.

getExtn

public java.lang.String getExtn()

Returns:

The extension of the file. This may be blank for files, and is always blank for directories. If not blank, it includes the prefix"."; thus name+file reconstructs the original rawname.

getQuery

public java.lang.String getQuery()

Returns:

The query string on the end of the file, if any. NB. does not include the separating '?' character itself.

toEncoded

public java.lang.String toEncoded()

Returns:

An encoded form of the entry which can safely be used in a URL.

See Also:

URLCoding.filepathToUrl(java.lang.String, char, boolean)

isFolder

public boolean isFolder()

Returns:

Whether this is a subfolder.

isAcceptable

public boolean isAcceptable()

Returns:

Whether this passed the file filter.

mainObject

public java.lang.Object mainObject()

Returns:

The "main object" which supplied the denormalised information we have here.

xmlMarshal

public void xmlMarshal(java.io.PrintWriter pw)
                throws java.io.IOException

Marshal the entry as XML. Typically this goes into a CXT document.

Throws:

java.io.IOException

xmlMarshal

public void xmlMarshal(java.io.PrintWriter pw,
                       boolean foldersOnly)
                throws java.io.IOException

Marshal the entry as XML. Typically this goes into a CXT document.

Throws:

java.io.IOException

sort

public static void sort(SortingFolderEntry[] contents)

Sort this array of folder entries into their proper order.

Parameters:

contents - The array to sort.

search

public static int search(SortingFolderEntry[] contents,
                         SortingFolderEntry key)

Find the index of the specified entry in the supplied array. The array must have been sorted previously (using sort) or the results are undefined.

Parameters:

contents - The sorted array to search in.

key - the entry to search for

Returns:

As java.util.Arrays.binarySearch

listFiles

public static SortingFolderEntry[] listFiles(java.io.File folderf,
                                             java.io.FileFilter filter)
                                      throws java.io.IOException

A helper method for the common special case where you need to generate a directory listing for a disk directory.

Parameters:

folderf - the folder (directory) whose contents are to be sorted. If null, the list of filesystem roots is returned.

filter - A FileFilter which determines whether a file is "acceptable" or not. Unacceptable files sort after acceptable and XML-marshal as badfile elements. Directories are always acceptable (the filter is bypassed for these). If the filter is null, all files are acceptable.

Returns:

The sorted list.

Throws:

java.io.IOException

xmlMarshalFolder

public static void xmlMarshalFolder(java.io.PrintWriter pw,
                                    SortingFolderEntry[] sfes,
                                    java.io.File folderf,
                                    java.lang.String filterPattern,
                                    boolean foldersOnly)
                             throws java.io.IOException

A helper method to marshal the current folder as XML, in the common special case where the folder is a disk file.

Parameters:

pw - where to write the XML to.

sfes - The content of the folder.

folderf - The folder being written.

filterPattern - The pattern of any filter applied sfes. May be null.

foldersOnly - Whether to only write subfolders.

Throws:

java.io.IOException

xmlMarshalFolder

public static void xmlMarshalFolder(java.io.PrintWriter pw,
                                    SortingFolderEntry[] sfes,
                                    java.lang.String folderPath,
                                    char separator,
                                    java.lang.String filterPattern,
                                    boolean includeUp,
                                    boolean foldersOnly)
                             throws java.io.IOException

A helper method to marshal the current folder as XML. If the current folder is a disk file, you should use the five-param version; this includes workarounds for various nastinesses to do with Win32's inability to handle removable media.

Parameters:

pw - where to write the XML to.

sfes - The content of the folder.

folderPath - The path of the folder being written.

separator - The path-element separator character for the filesystem this folder lives in.

filterPattern - The pattern of any filter applied sfes. May be null.

includeUp - Whether to include an entry for the "parent" directory, "..");

foldersOnly - Whether to only write subfolders.

Throws:

java.io.IOException