BaseXmlFileStorage.java

/**********************************************************************************
 * $URL: https://source.sakaiproject.org/svn/kernel/trunk/kernel-util/src/main/java/org/sakaiproject/util/BaseXmlFileStorage.java $
 * $Id: BaseXmlFileStorage.java 80991 2010-08-09 15:46:37Z david.horwitz@uct.ac.za $
 ***********************************************************************************
 *
 * Copyright (c) 2003, 2004, 2005, 2006, 2008 Sakai Foundation
 *
 * Licensed under the Educational Community License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *       http://www.opensource.org/licenses/ECL-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 **********************************************************************************/

package org.sakaiproject.util;

import java.util.Collections;
import java.util.Comparator;
import java.util.Enumeration;
import java.util.Hashtable;
import java.util.Iterator;
import java.util.List;
import java.util.Stack;
import java.util.Vector;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.sakaiproject.entity.api.Edit;
import org.sakaiproject.entity.api.Entity;
import org.sakaiproject.entity.api.ResourceProperties;
import org.sakaiproject.time.api.Time;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;

/**
 * <p>
 * BaseXmlFileStorage is a class that stores Resources (of some type) in an XML file <br />
 * backed memory store, provides locked access, and generally implements a service's <br />
 * "storage" class. The service's storage class can extend this to provide covers to <br />
 * turn Resource and Edit into something more type specific to the service.
 * </p>
 * @deprecated This was used in earlier versions of Sakai and isn't supported any longer.
 */
public class BaseXmlFileStorage
{
	/** Our logger. */
	private static Log M_log = LogFactory.getLog(BaseXmlFileStorage.class);

	/**
	 * Holds the container object, a table of the resources contained.
	 */
	protected class Container
	{
		/** The container Resource object. */
		public Entity container;

		/** The table of contained entry Resources. */
		public Hashtable contained;

		public Container(Entity c)
		{
			container = c;
			contained = new Hashtable();
		}
	}

	/** A full path and file name to the storage file. */
	protected String m_fileStoragePath = null;

	/** The xml tag name for the root element holding the multiple entries. */
	protected String m_rootTagName = null;

	/** The xml tag name for the element holding each container entry. */
	protected String m_containerTagName = null;

	/** The xml tag name for the element holding each actual entry. */
	protected String m_entryTagName = null;

	/** Two level store: Hashtables keyed by container ref of Container. */
	protected Hashtable m_store = null;

	/** Store all locks (across all containers), keyed by entry Resource reference. */
	protected Hashtable m_locks = null;

	/** The StorageUser to callback for new Resource and Edit objects. */
	protected StorageUser m_user = null;

	/** If set, we treat reasource ids as case insensitive. */
	protected boolean m_caseInsensitive = false;

	/**
	 * Construct.
	 * 
	 * @param path
	 *        The storage path.
	 * @param root
	 *        The xml tag name for the root element holding the multiple entries.
	 * @param container
	 *        The xml tag name for the element holding each container entry (may be null if there's no container structure and all entries are in the root).
	 * @param entry
	 *        The xml tag name for the element holding each actual entry.
	 * @param user
	 *        The StorageUser class to call back for creation of Resource and Edit objects.
	 */
	public BaseXmlFileStorage(String path, String root, String container, String entry, StorageUser user)
	{
		m_fileStoragePath = path;
		m_rootTagName = root;
		m_containerTagName = container;
		m_entryTagName = entry;
		m_user = user;
	}


	/**
	 * Load the Xml Document
	 */
	protected Document load()
	{
		return StorageUtils.readDocument(m_fileStoragePath);
	}

	/**
	 * Open and be ready to read / write.
	 */
	public void open()
	{
		// setup for resources
		m_store = new Hashtable();

		Container top = null;

		// put in a Top Container if we are not doing containers
		if (m_containerTagName == null)
		{
			top = new Container(null);
			m_store.put("", top);
		}

		// setup locks
		m_locks = new Hashtable();

		try
		{
			// read the xml
			Document doc = load();
			if (doc == null)
			{
				M_log.warn("missing user xml file: " + m_fileStoragePath);
				return;
			}

			// verify the root element
			Element root = doc.getDocumentElement();
			if (!root.getTagName().equals(m_rootTagName))
			{
				M_log.warn(".open(): root tag not: " + m_rootTagName + " found: " + root.getTagName());
				return;
			}

			// the children
			NodeList rootNodes = root.getChildNodes();
			final int rootNodesLength = rootNodes.getLength();
			for (int i = 0; i < rootNodesLength; i++)
			{
				Node rootNode = rootNodes.item(i);
				if (rootNode.getNodeType() != Node.ELEMENT_NODE) continue;
				Element rootElement = (Element) rootNode;

				// look for an entry element (entries in the root)
				if ((m_containerTagName == null) && (rootElement.getTagName().equals(m_entryTagName)))
				{
					// re-create the resource and store in the top container
					Entity entry = m_user.newResource(top.container, rootElement);

					top.contained.put(caseId(entry.getId()), entry);
				}

				// look for a container element (containers in the root, entries in the containers)
				else if ((m_containerTagName != null) && (rootElement.getTagName().equals(m_containerTagName)))
				{
					// re-create the container
					Entity containerResource = m_user.newContainer(rootElement);

					// add to the store
					Container container = new Container(containerResource);
					m_store.put(containerResource.getReference(), container);

					// scan for entry children of the container
					NodeList containerNodes = rootElement.getChildNodes();
					final int containerNodesLength = containerNodes.getLength();
					for (int j = 0; j < containerNodesLength; j++)
					{
						Node containerNode = containerNodes.item(j);
						if (containerNode.getNodeType() != Node.ELEMENT_NODE) continue;
						Element containerElement = (Element) containerNode;

						// look for an entry element (entries in the root)
						if (containerElement.getTagName().equals(m_entryTagName))
						{
							// re-create the resource
							Entity entry = m_user.newResource(container.container, containerElement);

							container.contained.put(caseId(entry.getId()), entry);
						}
					}
				}
			}
		}
		catch (Exception e)
		{
			M_log.warn(".open(): ", e);
		}
	}

	/**
	 * Create and return the XML Document for our storaghe
	 */
	protected Document createDocument()
	{
		// create the Dom with a root element
		Document doc = StorageUtils.createDocument();
		Stack stack = new Stack();
		Element root = doc.createElement(m_rootTagName);
		doc.appendChild(root);

		stack.push(root);

		// if we have no containers, store all elements from the Top container under the root
		if (m_containerTagName == null)
		{
			Enumeration e = ((Container) m_store.get("")).contained.elements();
			while (e.hasMoreElements())
			{
				Entity entry = (Entity) e.nextElement();
				entry.toXml(doc, stack);
			}
		}

		// otherwise, process each container
		else
		{
			Enumeration e = m_store.elements();
			while (e.hasMoreElements())
			{
				Container c = (Container) e.nextElement();

				// skip Top
				if (c.container == null) continue;

				// store the container
				Element containerElement = c.container.toXml(doc, stack);

				// push it onto the stack, so entries are created under it
				stack.push(containerElement);

				// store each contained under the container's element
				Enumeration elementEnum = c.contained.elements();
				while (elementEnum.hasMoreElements())
				{
					Entity entry = (Entity) elementEnum.nextElement();
					entry.toXml(doc, stack);
				}

				stack.pop();
			}
		}

		stack.pop();
		return doc;
	}

	/**
	 * flush
	 */
	protected void flush()
	{

		Document doc = createDocument();
		StorageUtils.writeDocument(doc, m_fileStoragePath);
	}

	/**
	 * Close.
	 */
	public void close()
	{

		flush();
		m_locks.clear();
		m_locks = null;
		m_store.clear();
		m_store = null;
	}

	/**
	 * Check if a container by this id exists.
	 * 
	 * @param ref
	 *        The container reference.
	 * @return true if a resource by this id exists, false if not.
	 */
	public boolean checkContainer(String ref)
	{
		Container c = ((Container) m_store.get(ref));
		return (c != null);
	}

	/**
	 * Get the container with this id, or null if not found.
	 * 
	 * @param ref
	 *        The container reference.
	 * @return The container with this id, or null if not found.
	 */
	public Entity getContainer(String ref)
	{
		if (ref == null) return null;
		Container c = ((Container) m_store.get(ref));
		if (c == null) return null;
		return c.container;
	}

	/**
	 * Get a list of all containers.
	 * 
	 * @return A list (Resource) of all containers, or empty if none defined.
	 */
	public List getAllContainers()
	{
		List rv = new Vector();

		if (m_containerTagName == null) return rv;
		if (m_store.size() == 0) return rv;

		Enumeration e = m_store.elements();
		while (e.hasMoreElements())
		{
			Container c = (Container) e.nextElement();
			rv.add(c.container);
		}

		return rv;
	}

	/**
	 * Add a new container with this id.
	 * 
	 * @param ref
	 *        The channel reference.
	 * @return The locked object with this id, or null if the id is in use.
	 */
	public Edit putContainer(String ref)
	{
		// if it's already defined
		Container c = ((Container) m_store.get(ref));
		if (c != null) return null;

		// make an Edit
		Edit edit = m_user.newContainerEdit(ref);

		synchronized (m_locks)
		{
			// if it's in the locks (i.e. it's been put() but not committed
			if (m_locks.get(edit.getReference()) != null) return null;

			// store it in the locks
			m_locks.put(edit.getReference(), edit);
		}

		return edit;
	}

	/**
	 * Return a lock on the container with this id, or null if a lock cannot be made.
	 * 
	 * @param ref
	 *        The container reference.
	 * @return The locked object with this id, or null if a lock cannot be made.
	 */
	public Edit editContainer(String ref)
	{
		Container c = (Container) m_store.get(ref);
		if (c == null) return null;

		synchronized (m_locks)
		{
			// check for a lock in place
			if (m_locks.get(c.container.getReference()) != null) return null;

			// make an Edit
			Edit edit = m_user.newContainerEdit(c.container);

			// store it in the locks
			m_locks.put(edit.getReference(), edit);

			return edit;
		}
	}

	/**
	 * Commit the changes and release the locked container.
	 * 
	 * @param container
	 *        The container id.
	 * @param edit
	 *        The entry to commit.
	 */
	public void commitContainer(Edit edit)
	{
		// make a new Entry from the Edit to update the info store
		Entity updatedContainer = m_user.newContainer(edit);

		// update the store
		Container c = ((Container) m_store.get(updatedContainer.getReference()));
		if (c != null)
		{
			c.container = updatedContainer;
		}
		else
		{
			c = new Container(updatedContainer);
			m_store.put(updatedContainer.getReference(), c);
		}

		// release the lock
		m_locks.remove(edit.getReference());
	}

	/**
	 * Cancel the changes and release the locked container.
	 * 
	 * @param container
	 *        The container id.
	 * @param edit
	 *        The entry to cancel.
	 */
	public void cancelContainer(Edit edit)
	{
		// release the lock
		m_locks.remove(edit.getReference());
	}

	/**
	 * Remove this container and all it contains.
	 * 
	 * @param container
	 *        The container id.
	 * @param edit
	 *        The entry to remove.
	 */
	public void removeContainer(Edit edit)
	{
		Container c = ((Container) m_store.get(edit.getReference()));
		if (c != null)
		{
			m_store.remove(c);
			// %%% better cleanup?
		}

		// release the lock
		m_locks.remove(edit.getReference());
	}

	/**
	 * Check if a resource by this id exists.
	 * 
	 * @param container
	 *        The container id.
	 * @param id
	 *        The id.
	 * @return true if a resource by this id exists, false if not.
	 */
	public boolean checkResource(String container, String id)
	{
		if (container == null) container = "";
		Container c = ((Container) m_store.get(container));
		if (c == null) return false;

		return c.contained.get(caseId(id)) != null;
	}

	/**
	 * Get the entry with this id, or null if not found.
	 * 
	 * @param container
	 *        The container id.
	 * @param id
	 *        The id.
	 * @return The entry with this id, or null if not found.
	 */
	public Entity getResource(String container, String id)
	{
		if (container == null) container = "";
		Container c = ((Container) m_store.get(container));
		if (c == null) return null;

		return (Entity) c.contained.get(caseId(id));
	}

	/**
	 * Get all entries.
	 * 
	 * @param container
	 *        The container id.
	 * @return The list (Resource) of all entries.
	 */
	public List getAllResources(String container)
	{
		List rv = new Vector();

		if (container == null) container = "";
		Container c = ((Container) m_store.get(container));
		if (c == null) return rv;
		if (c.contained.size() == 0) return rv;

		rv.addAll(c.contained.values());
		return rv;
	}

	/**
	 * Determine if empty
	 * 
	 * @return true if empty, false if not.
	 */
	public boolean isEmpty(String container)
	{
		if (container == null) container = "";
		Container c = ((Container) m_store.get(container));
		if (c == null) return true;
		if (c.contained.size() == 0) return true;

		return false;
	}

	/**
	 * Get all entries within a range sorted by id.
	 * 
	 * @param container
	 *        The container id.
	 * @param first
	 *        The first position.
	 * @param last
	 *        The last position.
	 * @return The list (Resource) of all entries within a range sorted by id.
	 */
	public List getAllResources(String container, int first, int last)
	{
		List rv = new Vector();

		if (container == null) container = "";
		Container c = ((Container) m_store.get(container));
		if (c == null) return rv;
		if (c.contained.size() == 0) return rv;

		rv.addAll(c.contained.values());

		Collections.sort(rv);

		// subset by position
		if (first < 1) first = 1;
		if (last >= rv.size()) last = rv.size();

		rv = rv.subList(first - 1, last);

		return rv;
	}

	/**
	 * Count all entries.
	 * 
	 * @param container
	 *        The container id.
	 * @return The count of all entries.
	 */
	public int countAllResources(String container)
	{
		if (container == null) container = "";
		Container c = ((Container) m_store.get(container));
		if (c == null) return 0;
		return c.contained.size();
	}

	/**
	 * Add a new entry with this id.
	 * 
	 * @param container
	 *        The container id.
	 * @param id
	 *        The id.
	 * @param others
	 *        Other fields for the newResource call
	 * @return The locked object with this id, or null if the id is in use.
	 */
	public Edit putResource(String container, String id, Object[] others)
	{
		if (container == null) container = "";
		Container c = ((Container) m_store.get(container));
		if (c == null) return null;

		// if it's already defined
		if (c.contained.get(caseId(id)) != null) return null;

		// make an Edit
		Edit edit = m_user.newResourceEdit(c.container, id, others);

		synchronized (m_locks)
		{
			// if it's in the locks (i.e. it's been put() but not committed
			if (m_locks.get(edit.getReference()) != null) return null;

			// store it in the locks
			m_locks.put(edit.getReference(), edit);
		}

		return edit;
	}

	/**
	 * Return a lock on the entry with this id, or null if a lock cannot be made.
	 * 
	 * @param container
	 *        The container id.
	 * @param id
	 *        The id.
	 * @return The locked object with this id, or null if a lock cannot be made.
	 */
	public Edit editResource(String container, String id)
	{
		if (container == null) container = "";
		Container c = ((Container) m_store.get(container));
		if (c == null) return null;

		Entity entry = (Entity) c.contained.get(caseId(id));
		if (entry == null) return null;

		synchronized (m_locks)
		{
			// check for a lock in place
			if (m_locks.get(entry.getReference()) != null) return null;

			// make an Edit
			Edit edit = m_user.newResourceEdit(c.container, entry);

			// store it in the locks
			m_locks.put(entry.getReference(), edit);

			return edit;
		}
	}

	/**
	 * Commit the changes and release the lock.
	 * 
	 * @param container
	 *        The container id.
	 * @param edit
	 *        The entry to commit.
	 */
	public void commitResource(String container, Edit edit)
	{
		if (container == null) container = "";
		Container c = ((Container) m_store.get(container));
		if (c != null)
		{
			// make a new Entry from the Edit to update the info store
			Entity updatedEntry = m_user.newResource(c.container, edit);

			c.contained.put(caseId(updatedEntry.getId()), updatedEntry);
		}

		// release the lock
		m_locks.remove(edit.getReference());
	}

	/**
	 * Cancel the changes and release the lock.
	 * 
	 * @param container
	 *        The container id.
	 * @param edit
	 *        The entry to cancel.
	 */
	public void cancelResource(String container, Edit edit)
	{
		// release the lock
		m_locks.remove(edit.getReference());
	}

	/**
	 * Remove this entry.
	 * 
	 * @param container
	 *        The container id.
	 * @param edit
	 *        The entry to remove.
	 */
	public void removeResource(String container, Edit edit)
	{
		if (container == null) container = "";
		Container c = ((Container) m_store.get(container));
		if (c != null)
		{
			// remove from the info store
			c.contained.remove(caseId(edit.getId()));
		}

		// release the lock
		m_locks.remove(edit.getReference());
	}

	/**
	 * Fix the case of resource ids to support case insensitive ids if enabled
	 * 
	 * @param The
	 *        id to fix.
	 * @return The id, case modified as needed.
	 */
	protected String caseId(String id)
	{
		if (m_caseInsensitive)
		{
			return id.toLowerCase();
		}

		return id;
	}

	/**
	 * Enable / disable case insensitive ids.
	 * 
	 * @param setting
	 *        true to set case insensitivity, false to set case sensitivity.
	 */
	protected void setCaseInsensitivity(boolean setting)
	{
		m_caseInsensitive = setting;
	}

	/**
	 * Get resources filtered by date and count and drafts, in descending (latest first) order
	 * 
	 * @param container
	 *        The container id.
	 * @param afterDate
	 *        if null, no date limit, else limited to only messages after this date.
	 * @param limitedToLatest
	 *        if 0, no count limit, else limited to only the latest this number of messages.
	 * @param draftsForId
	 *        how to handle drafts: null means no drafts, "*" means all, otherwise drafts only if created by this userId.
	 * @param pubViewOnly
	 *        if true, include only messages marked pubview, else include any.
	 * @return A list of Message objects that meet the criteria; may be empty
	 */
	public List getResources(String container, Time afterDate, int limitedToLatest, String draftsForId, boolean pubViewOnly)
	{
		if (container == null) container = "";
		Container c = ((Container) m_store.get(container));
		if (c == null) return new Vector();
		if (c.contained.size() == 0) return new Vector();

		List all = new Vector();
		all.addAll(c.contained.values());

		// sort latest date first
		Collections.sort(all, new Comparator()
		{
			public int compare(Object o1, Object o2)
			{
				// if the same object
				if (o1 == o2) return 0;

				// assume they are Resource
				Entity r1 = (Entity) o1;
				Entity r2 = (Entity) o2;

				// get each one's date
				Time t1 = m_user.getDate(r1);
				Time t2 = m_user.getDate(r2);

				// compare based on date
				int compare = t2.compareTo(t1);

				return compare;
			}
		});

		// early out - if no filtering needed
		if ((limitedToLatest == 0) && (afterDate == null) && ("*".equals(draftsForId)) && !pubViewOnly)
		{
			return all;
		}

		Vector selected = new Vector();

		// deal with drafts / date / pubview
		for (Iterator i = all.iterator(); i.hasNext();)
		{
			Entity r = (Entity) i.next();
			Entity candidate = null;
			if (m_user.isDraft(r))
			{
				// if some drafts
				if ((draftsForId != null) && (m_user.getOwnerId(r).equals(draftsForId)))
				{
					candidate = r;
				}
			}
			else
			{
				candidate = r;
			}

			// deal with date if it passes the draft criteria
			if ((candidate != null) && (afterDate != null))
			{
				if (m_user.getDate(candidate).before(afterDate))
				{
					candidate = null;
				}
			}

			// if we want pub view only
			if ((candidate != null) && pubViewOnly)
			{
				if (candidate.getProperties().getProperty(ResourceProperties.PROP_PUBVIEW) == null)
				{
					candidate = null;
				}
			}

			// add it if it passes all criteria
			if (candidate != null)
			{
				selected.add(candidate);
			}
		}

		// pick what we need
		if ((limitedToLatest > 0) && (limitedToLatest < selected.size()))
		{
			all = selected.subList(0, limitedToLatest);
		}
		else
		{
			all = selected;
		}

		return all;
	}

	/**
	 * Access a list of container ids that match (start with) the root.
	 * 
	 * @param context
	 *        The reference root to match.
	 * @return A List (String) of container id which match the root.
	 */
	public List getContainerIdsMatching(String context)
	{
		List containers = getAllContainers();
		List rv = new Vector();

		// the id of each container will be the part that follows the root reference
		final int pos = context.length();

		// filter
		for (Iterator i = containers.iterator(); i.hasNext();)
		{
			Entity r = (Entity) i.next();
			String ref = r.getReference();
			if (ref.startsWith(context))
			{
				// check the reference, return the id (what follows the root)
				String id = ref.substring(pos);
				rv.add(id);
			}
		}

		return rv;
	}
}