com.mucommander.bookmark
Class BookmarkManager

java.lang.Object
  com.mucommander.bookmark.BookmarkManager

All Implemented Interfaces:

VectorChangeListener

public class BookmarkManager
extends java.lang.Object
implements VectorChangeListener

This class manages the boomark list and its parsing and storage as an XML file.

It monitors any changes made to the bookmarks and when changes are made, fires change events to registered listeners.

Author:

Maxence Bernard, Nicolas Rinaudo

Method Summary

static void	addBookmark(Bookmark b) Convenience method that adds a bookmark to the bookmark list.
static void	addBookmarkListener(BookmarkListener listener) Adds the specified BookmarkListener to the list of registered listeners.
static void	buildBookmarks(BookmarkBuilder builder) Passes messages about all known bookmarks to the specified builder.
void	elementChanged(int index) This method is called when an element has been changed in the AlteredVector.
void	elementsAdded(int startIndex, int nbAdded) This method is called when one or more elements has been added to the AlteredVector.
void	elementsRemoved(int startIndex, int nbRemoved) This method is called when one or more elements has been removed from the AlteredVector.
static void	fireBookmarksChanged() Notifies all the registered bookmark listeners of a bookmark change.
static Bookmark	getBookmark(java.lang.String name) Convenience method that looks for a Bookmark with the given name (case ignored) and returns it, or null if none was found.
static AlteredVector	getBookmarks() Returns an AlteredVector that contains all bookmarks.
static AbstractFile	getBookmarksFile() Returns the path to the bookmark file.
static BookmarkBuilder	getBookmarkWriter(java.io.OutputStream out) Returns a BookmarkBuilder that will write all building messages as XML to the specified output stream.
static void	loadBookmarks() Loads all available bookmarks.
static void	readBookmarks(java.io.InputStream in) Reads bookmarks from the specified InputStream.
static void	readBookmarks(java.io.InputStream in, BookmarkBuilder builder) Reads bookmarks from the specified InputStream and passes messages to the specified BookmarkBuilder.
static void	removeBookmark(Bookmark bookmark) Deletes the specified bookmark.
static void	removeBookmarkListener(BookmarkListener listener) Removes the specified BookmarkListener from the list of registered listeners.
static void	setBookmarksFile(AbstractFile file) Sets the path to the bookmarks file.
static void	setBookmarksFile(java.io.File file) Sets the path to the bookmarks file.
static void	setBookmarksFile(java.lang.String path) Sets the path to the bookmarks file.
static void	setFireEvents(boolean b) Specifies whether bookmark events should be fired when a change in the bookmarks is detected.
static void	writeBookmarks(boolean forceWrite) Writes all known bookmarks to the bookmark file.

Methods inherited from class java.lang.Object

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

Method Detail

buildBookmarks

public static void buildBookmarks(BookmarkBuilder builder)
                           throws BookmarkException

Passes messages about all known bookmarks to the specified builder.

Parameters:

builder - where to send bookmark building messages.

Throws:

BookmarkException - if an error occurs.

getBookmarksFile

public static AbstractFile getBookmarksFile()
                                     throws java.io.IOException

Returns the path to the bookmark file.

If it hasn't been changed through a call to setBookmarksFile(String), this method will return the default, system dependant bookmarks file.

Returns:

the path to the bookmark file.

Throws:

java.io.IOException - if there was a problem locating the default bookmarks file.

See Also:

setBookmarksFile(String)

setBookmarksFile

public static void setBookmarksFile(java.lang.String path)
                             throws java.io.FileNotFoundException

Sets the path to the bookmarks file.

This is a convenience method and is strictly equivalent to calling setBookmarksFile(FileFactory.getFile(file)).

Parameters:

path - path to the bookmarks file

Throws:

java.io.FileNotFoundException - if path is not accessible.

See Also:

getBookmarksFile()

setBookmarksFile

public static void setBookmarksFile(java.io.File file)
                             throws java.io.FileNotFoundException

Sets the path to the bookmarks file.

This is a convenience method and is strictly equivalent to calling setBookmarksFile(FileFactory.getFile(file.getAbsolutePath())).

Parameters:

file - path to the bookmarks file

Throws:

java.io.FileNotFoundException - if path is not accessible.

See Also:

getBookmarksFile()

setBookmarksFile

public static void setBookmarksFile(AbstractFile file)
                             throws java.io.FileNotFoundException

Sets the path to the bookmarks file.

Parameters:

file - path to the bookmarks file

Throws:

java.io.FileNotFoundException - if path is not accessible.

See Also:

getBookmarksFile()

loadBookmarks

public static void loadBookmarks()
                          throws java.lang.Exception

Loads all available bookmarks.

Throws:

java.lang.Exception - if an error occurs.

readBookmarks

public static void readBookmarks(java.io.InputStream in)
                          throws java.lang.Exception

Reads bookmarks from the specified InputStream.

Parameters:

in - where to read bookmarks from.

Throws:

java.lang.Exception - if an error occurs.

readBookmarks

public static void readBookmarks(java.io.InputStream in,
                                 BookmarkBuilder builder)
                          throws java.lang.Exception

Reads bookmarks from the specified InputStream and passes messages to the specified BookmarkBuilder.

Parameters:

in - where to read bookmarks from.

builder - where to send builing messages to.

Throws:

java.lang.Exception - if an error occurs.

getBookmarkWriter

public static BookmarkBuilder getBookmarkWriter(java.io.OutputStream out)
                                         throws java.io.IOException

Returns a BookmarkBuilder that will write all building messages as XML to the specified output stream.

Parameters:

out - where to write the bookmarks' XML content.

Returns:

a BookmarkBuilder that will write all building messages as XML to the specified output stream.

Throws:

java.io.IOException - if an IO related error occurs.

writeBookmarks

public static void writeBookmarks(boolean forceWrite)
                           throws java.io.IOException,
                                  BookmarkException

Writes all known bookmarks to the bookmark file.

Parameters:

forceWrite - if false, the bookmarks file will be written only if changes were made to bookmarks since last write, if true the file will always be written

Throws:

java.io.IOException - if an I/O error occurs.

BookmarkException - if an error occurs.

getBookmarks

public static AlteredVector getBookmarks()

Returns an AlteredVector that contains all bookmarks.

Important: the returned Vector should not directly be used to add or remove bookmarks, doing so won't trigger any event to registered bookmark listeners. However, it is safe to modify bookmarks individually, events will be properly fired.

Returns:

an AlteredVector that contains all bookmarks.

removeBookmark

public static void removeBookmark(Bookmark bookmark)

Deletes the specified bookmark.

Parameters:

bookmark - bookmark to delete from the list.

getBookmark

public static Bookmark getBookmark(java.lang.String name)

Convenience method that looks for a Bookmark with the given name (case ignored) and returns it, or null if none was found. If several bookmarks have the given name, the first one is returned.

Parameters:

name - the bookmark's name

Returns:

a Bookmark instance with the given name, null if none was found

addBookmark

public static void addBookmark(Bookmark b)

Convenience method that adds a bookmark to the bookmark list.

Parameters:

b - the Bookmark instance to add to the bookmark list.

addBookmarkListener

public static void addBookmarkListener(BookmarkListener listener)

Adds the specified BookmarkListener to the list of registered listeners.

Listeners are stored as weak references so removeBookmarkListener(BookmarkListener) doesn't need to be called for listeners to be garbage collected when they're not used anymore.

Parameters:

listener - the BookmarkListener to add to the list of registered listeners.

See Also:

removeBookmarkListener(BookmarkListener)

removeBookmarkListener

public static void removeBookmarkListener(BookmarkListener listener)

Removes the specified BookmarkListener from the list of registered listeners.

Parameters:

listener - the BookmarkListener to remove from the list of registered listeners.

See Also:

addBookmarkListener(BookmarkListener)

fireBookmarksChanged

public static void fireBookmarksChanged()

Notifies all the registered bookmark listeners of a bookmark change. This can be :

• A new bookmark which has just been added
• An existing bookmark which has been modified
• An existing bookmark which has been removed

setFireEvents

public static void setFireEvents(boolean b)

Specifies whether bookmark events should be fired when a change in the bookmarks is detected. This allows to temporarily suspend events firing when a lot of them are made, for example when editing the bookmarks list.

If true is speicified, any subsequent calls to fireBookmarksChanged will be ignored, until this method is called again with false.

Parameters:

b - whether to fire events.

elementsAdded

public void elementsAdded(int startIndex,
                          int nbAdded)

Description copied from interface: VectorChangeListener

This method is called when one or more elements has been added to the AlteredVector.

Specified by:

elementsAdded in interface VectorChangeListener

Parameters:

startIndex - index at which the first element has been added

nbAdded - number of elements added

elementsRemoved

public void elementsRemoved(int startIndex,
                            int nbRemoved)

Description copied from interface: VectorChangeListener

This method is called when one or more elements has been removed from the AlteredVector.

Specified by:

elementsRemoved in interface VectorChangeListener

Parameters:

startIndex - index at which the first element has been removed

nbRemoved - number of elements removed

elementChanged

public void elementChanged(int index)

Description copied from interface: VectorChangeListener

This method is called when an element has been changed in the AlteredVector.

Specified by:

elementChanged in interface VectorChangeListener

Parameters:

index - index of the element that has been changed