org.rakeshv.xml.addressbook
Class AddressBook

java.lang.Object
  org.rakeshv.xml.addressbook.AddressBook

public class AddressBook
extends java.lang.Object

Address book implementation. This class presents a java view of the specified address book xml file. This class also contains methods for creating new address book entries, and for deleted existing entries. This class should ideally be cached in the servlet containers servlet context for maximum performance, since it can take quite a long time to build the JDOM tree if the address book is large.

You can use the createAddressBook( String ) method to create a new AddressBook specified by the fully qualified file name specified in the method call.

Copyright 2003 Rakesh Vidyadharan

Version:

$Id: AddressBook.java,v 1.7 2004/10/16 19:17:02 rakesh Exp $

Author:

Rakesh Vidyadharan 2003 February 11

Field Summary

private org.jdom.Document	document A reference to the address book XML document.
private java.lang.String	fileName The fully qualified name of the address book XML file.
private java.util.Map	groups The map of Group records.
private org.jdom.Element	groupsElement A reference to the element that contains all the group entries (groups).
(package private) org.jdom.Namespace	namespace The namespace for the root element.
private java.util.Map	persons The map of Person records.
private org.jdom.Element	personsElement A reference to the element that contains all the person entries (persons).

Constructor Summary

protected	AddressBook() Default constructor.
	AddressBook(java.lang.String fileName) Just invoke AddressBook( String, String ) with a value of null for the preferred SAX Parser to use.
	AddressBook(java.lang.String fileName, java.lang.String saxParser) Load the specified address book XML file using the specified SAX Parser.

Method Summary

private void	addAddress(java.util.List list, org.jdom.Element component) Add the Address objects in the specified list to the specified element.
void	addGroup(Group group) Add the specified Group to the address book.
private void	addGroupToTree(Group group) Add the specified Group object under the groupsElement node in the JDOM tree.
void	addPerson(Person person) Add the specified Person java bean to the address book.
private void	addPersonToTree(Person person) Add the specified Person object to the JDOM tree as a person element.
static AddressBook	createAddressBook(java.lang.String file) Just invokes createAddressBook( String, String ) with a null value for the default SAX Parser.
static AddressBook	createAddressBook(java.lang.String file, java.lang.String saxParser) Create a new address book using the fully qualified file name specified, and using the specified SAX Parser to load the XML file that has been created.
boolean	deleteGroup(java.lang.String nickname) Delete the Group identified by the Group.nickname specified from the address book.
boolean	deleteGroups(java.lang.String[] nicknames) Delete the Group's identified by the Group.nickname's specified from the address book.
boolean	deletePerson(java.lang.String nickname) Remove the Person identified by the specified Person.nickname.
boolean	deletePersons(java.lang.String[] nicknames) Remove the Person's identified by the specified Person.nicknames.
java.util.Map	getGroups() Return the value/reference of the groups.
java.util.Map	getPersons() Return the value/reference of the persons.
private void	loadAddressBook(java.lang.String saxParser) Load the address book XML file (fileName) using JDOM, and populate the class fields persons and groups.
void	modifyAssociatedGroup(Person person) Find the associated Group in the groups Map (if any), and change the Member.mail to the Person.mail of the Person object passed in.
void	modifyGroup(Group group) Modify the specified Group in the address book.
void	modifyPerson(Person person) Save the specified Person java bean that has been modified to the underlying JDOM tree.
private void	populateAddresses(Person person, org.jdom.Element personElement) Populate the Person.addresses list, if address data is available for the specified person element in the address book.
private Group	populateGroup(org.jdom.Element group) Walk through the child elements of the specified group element, and create a Group object out of the contents.
private void	populateGroups() Walk through the JDOM tree, and populate the groups list of Group objects.
private Person	populatePerson(org.jdom.Element element) Walk through the child elements of the specified person element, and create a corresponding Person bean.
private void	populatePersons() Walk through the JDOM tree, and populate the persons Map of Person objects.
void	saveAddressBook() Write the JDOM tree back to the address book file.
void	setFileName(java.lang.String fileName) Set the value of fileName.

Methods inherited from class java.lang.Object

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

Field Detail

fileName

private java.lang.String fileName

The fully qualified name of the address book XML file.

persons

private java.util.Map persons

The map of Person records. This corresponds to all the person elements under the persons element in the address book. The map is populated using the Person.nickname as the key.

groups

private java.util.Map groups

The map of Group records. This corresponds to all the group elements under the groups element in the address book. The map is populated using the Group.nickname as the key.

document

private org.jdom.Document document

A reference to the address book XML document.

namespace

org.jdom.Namespace namespace

The namespace for the root element.

personsElement

private org.jdom.Element personsElement

A reference to the element that contains all the person entries (persons).

groupsElement

private org.jdom.Element groupsElement

A reference to the element that contains all the group entries (groups).

Constructor Detail

AddressBook

protected AddressBook()

Default constructor. Cannot be directly called.

AddressBook

public AddressBook(java.lang.String fileName)
            throws AddressException

Just invoke AddressBook( String, String ) with a value of null for the preferred SAX Parser to use.

Parameters:

fileName - - The fully qualified name of the address book XML file.

Throws:

AddressException - - If any JDOM/IOExceptions are encountered while processing the address book XML file.

AddressBook

public AddressBook(java.lang.String fileName,
                   java.lang.String saxParser)
            throws AddressException

Load the specified address book XML file using the specified SAX Parser.

Parameters:

fileName - - The fully qualified name of the address book XML file.

saxParser - - The full class name of the preferred SAX Parser to use.

Throws:

AddressException - - If any JDOM/IOExceptions are encountered while processing the address book XML file.

See Also:

loadAddressBook( String )

Method Detail

loadAddressBook

private void loadAddressBook(java.lang.String saxParser)
                      throws AddressException

Load the address book XML file (fileName) using JDOM, and populate the class fields persons and groups.

Parameters:

saxParser - - The full class name of the SAX Parser to use. If this is null the default JAXP SAX Parser will be used.

Throws:

AddressException - - If any JDOM/IOExceptions are encountered while processing the address book XML file.

See Also:

populatePersons(), populateGroups()

populatePersons

private void populatePersons()

Walk through the JDOM tree, and populate the persons Map of Person objects. Fetches all the children of the personsElement root Element in the address book XML file.

See Also:

populatePerson( Element )

populatePerson

private Person populatePerson(org.jdom.Element element)

Walk through the child elements of the specified person element, and create a corresponding Person bean.

Parameters:

element - - The current person element.

Returns:

Person - The java bean that was created with the child elements of the specified person element.

populateAddresses

private void populateAddresses(Person person,
                               org.jdom.Element personElement)

Populate the Person.addresses list, if address data is available for the specified person element in the address book.

Parameters:

person - - The java bean to which the address list is to be added.

personElement - - The person element in which to look for address information.

populateGroups

private void populateGroups()

Walk through the JDOM tree, and populate the groups list of Group objects. Fetches all the children under the groupsElement root Element in the address book XML file.

See Also:

populateGroup( Element )

populateGroup

private Group populateGroup(org.jdom.Element group)

Walk through the child elements of the specified group element, and create a Group object out of the contents.

Parameters:

group - - The specific group element to process.

addPerson

public void addPerson(Person person)
               throws AddressException

Add the specified Person java bean to the address book. This method checks to make sure that an entry with the same Person.nickname does not exist in the persons Map. The specified Person object is added both to the persons Map, as well as to the JDOM tree.

Note:This method does not write the modified JDOM tree back to the address book file. To save your modifications, please use the saveAddressBook() method.

Parameters:

person - - The java bean with all the information pertaining to a person entry in the address book.

Throws:

AddressException - - If the specified Person has an identical Person.nickname as an existing entry in the persons Map.

See Also:

addPersonToTree( Person )

modifyPerson

public void modifyPerson(Person person)

Save the specified Person java bean that has been modified to the underlying JDOM tree. The easiest way to do this is to remove the existing person element, and add the modified Person bean as a new child element of the persons element using addPersonToTree( Person ).

Note:This method does not write the modified JDOM tree back to the address book file. To save your modifications, please use the saveAddressBook() method.

Parameters:

person - - The java bean with all the information pertaining to a person entry in the address book.

addPersonToTree

private void addPersonToTree(Person person)

Add the specified Person object to the JDOM tree as a person element.

Note:This method does not write the modified JDOM tree back to the address book file. To save your modifications, please use the saveAddressBook() method.

Parameters:

person - - The java bean with all the information pertaining to a person entry in the address book.

deletePersons

public boolean deletePersons(java.lang.String[] nicknames)

Remove the Person's identified by the specified Person.nicknames. This method removes the Person's from the persons Map as well as the appropriate element from the underlying JDOM tree. This method just iterates through the array, and invokes deletePerson( String ) to delete each Person specified.

Parameters:

nicknames - - The nickname of the person that is to be removed.

Returns:

boolean - Returns true if the nickname exists in the persons Map, and false otherwise. A return value of false indicates that not all the specified persons could be deleted, as not all of them were valid.

deletePerson

public boolean deletePerson(java.lang.String nickname)

Remove the Person identified by the specified Person.nickname. This method removes the Person from the persons Map as well as the appropriate element from the underlying JDOM tree.

Parameters:

nickname - - The nickname of the person that is to be removed.

Returns:

boolean - Returns true if the nickname exists in the persons Map, and false otherwise.

addAddress

private void addAddress(java.util.List list,
                        org.jdom.Element component)

Add the Address objects in the specified list to the specified element.

Parameters:

list - - The list containing the addresses for the person.

component - - The element to which the addresses are to be added.

addGroup

public void addGroup(Group group)
              throws AddressException

Add the specified Group to the address book. This method checks to make sure that a Group with the Group.nickname does not exist in the groups Map. This method adds the specified Group to the groups Map as well as the JDOM tree.

Note:This method does not save the modification to the JDOM tree to the address book xml file. Please use the saveAddressBook() method, if you wish to save your changes.

Parameters:

group - - The new group that is to be added to the address book.

Throws:

AddressException - - If the specified Group has an identical Group.nickname as an existing entry in the groups Map.

modifyGroup

public void modifyGroup(Group group)

Modify the specified Group in the address book. This method modifies the specified Group in the groups Map as well as the under-lying element in the JDOM tree.

Note:This method does not save the modification to the JDOM tree to the address book xml file. Please use the saveAddressBook() method, if you wish to save your changes.

Parameters:

group - - The new group that is to be added to the address book.

See Also:

addGroupToTree( Group )

addGroupToTree

private void addGroupToTree(Group group)

Add the specified Group object under the groupsElement node in the JDOM tree.

Parameters:

group - - The group bean that is to be added.

modifyAssociatedGroup

public void modifyAssociatedGroup(Person person)

Find the associated Group in the groups Map (if any), and change the Member.mail to the Person.mail of the Person object passed in. If an associated Group is found, also modify the underlying JDOM tree.

Note:This method does not save the modification to the JDOM tree to the address book xml file. Please use the saveAddressBook() method, if you wish to save your changes.

deleteGroups

public boolean deleteGroups(java.lang.String[] nicknames)

Delete the Group's identified by the Group.nickname's specified from the address book. This method deletes the specified Group's from the groups Map as well as the under-lying elements in the JDOM tree. This method simply iterates through the entries in the array, and invokes deleteGroup( String ) to delete the individual entry.

Note:This method does not save the modification to the JDOM tree to the address book xml file. Please use the saveAddressBook() method, if you wish to save your changes.

Parameters:

nicknames - - The groups that are to be deleted.

Returns:

boolean - Returns true if the specified nicknames exists in the groups Map. If not it returns false. A return value of false indicates that some/all of the groups specified could not be deleted, as they are not valid groups.

deleteGroup

public boolean deleteGroup(java.lang.String nickname)

Delete the Group identified by the Group.nickname specified from the address book. This method deletes the specified Group from the groups Map as well as the under-lying element in the JDOM tree.

Note:This method does not save the modification to the JDOM tree to the address book xml file. Please use the saveAddressBook() method, if you wish to save your changes.

Parameters:

nickname - - The group that is to be deleted.

Returns:

boolean - Returns true if the specified nickname exists in the groups Map. If not it returns false.

saveAddressBook

public void saveAddressBook()
                     throws AddressException

Write the JDOM tree back to the address book file.

Throws:

AddressException - - If any exceptions are encountered while serialising the JDOM tree to the address book file.

createAddressBook

public static AddressBook createAddressBook(java.lang.String file)
                                     throws AddressException

Just invokes createAddressBook( String, String ) with a null value for the default SAX Parser.

Parameters:

file - - The fully qualified name of the file ie. the full path and name of file to use as the address book.

Throws:

AddressException - - If any exceptions are encountered while creating or writing to the specified file.

createAddressBook

public static AddressBook createAddressBook(java.lang.String file,
                                            java.lang.String saxParser)
                                     throws AddressException

Create a new address book using the fully qualified file name specified, and using the specified SAX Parser to load the XML file that has been created.

Parameters:

file - - The fully qualified name of the file ie. the full path and name of file to use as the address book.

saxParser - - The full class name of the preferred SAX Parser. If this is null the default JAXP SAX Parser will be used.

Throws:

AddressException - - If any exceptions are encountered while creating or writing to the specified file.

getPersons

public final java.util.Map getPersons()

Return the value/reference of the persons.

Returns:

Map - The value/reference of persons.

getGroups

public final java.util.Map getGroups()

Return the value/reference of the groups.

Returns:

Map - The value/reference of groups.

setFileName

public final void setFileName(java.lang.String fileName)

Set the value of fileName.

Parameters:

fileName - - The value to set.