tapestry-framework/src/java/org/apache/tapestry/util/DefaultPrimaryKeyConverter.java

// Copyright 2005 The Apache Software Foundation
//
// Licensed under the Apache 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.apache.org/licenses/LICENSE-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.apache.tapestry.util;

import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;

import org.apache.hivemind.ApplicationRuntimeException;
import org.apache.hivemind.util.Defense;
import org.apache.tapestry.components.IPrimaryKeyConverter;

/**
 * Companion to the {@link org.apache.tapestry.components.ForBean For component}, this class is an
 * implementation of {@link org.apache.tapestry.components.IPrimaryKeyConverter} that performs some
 * additional handling, such as tracking value sets..
 * <p>
 * Value sets are sets of value objects maintained by the converter; the converter will provide a
 * synthetic read/write boolean property that indicates if the {@link #getLastValue() last value} is
 * or is not in the set.
 * <p>
 * A single built-in value set, {@link #isDeleted()} has a special purpose; it controls whether or
 * not values are returned from {@link #getValues()}. Subclasses may add additional synthetic
 * boolean properties and additional sets.
 * <p>
 * Why not just store a boolean property in the object itself? Well, deleted is a good example of a
 * property that is meaningful in the context of an operation, but isn't stored ... once an object
 * is deleted (from secondary storage, such as a database) there's no place to store such a flag.
 * The DefaultPrimaryKey converter is used in this context to store transient, operation data ...
 * such as which values are to be deleted.
 * <p>
 * This class can be thought of as a successor to {@link org.apache.tapestry.form.ListEditMap}.
 * 
 * @author Howard M. Lewis Ship
 * @since 4.0
 */
public class DefaultPrimaryKeyConverter implements IPrimaryKeyConverter
{
    private final Map _map = new HashMap();

    private final List _keys = new ArrayList();

    // The values added to the Map, in the order they were added.
    private final List _values = new ArrayList();

    // The last value accessed by getPrimaryKey() or getValue().
    // Other methods may operate upon this value.

    private Object _lastValue;

    private Set _deletedValues;

    /**
     * Clears all properties of the converter, returning it to a pristine state. Subclasses should
     * invoke this implementation in addition to clearing any of their own state.
     */
    public void clear()
    {
        _map.clear();
        _keys.clear();
        _values.clear();
        _lastValue = null;
        _deletedValues = null;
    }

    public final void add(Object key, Object value)
    {
        Defense.notNull(key, "key");
        Defense.notNull(value, "value");

        if (_map.containsKey(key))
            throw new ApplicationRuntimeException(UtilMessages.keyAlreadyExists(key));

        _map.put(key, value);

        _keys.add(key);
        _values.add(value);

        _lastValue = value;
    }

    /**
     * Returns a unmodifiable list of values stored into the converter, in the order in which they
     * were stored.
     * 
     * @return an unmodifiable List
     * @see #add(Object, Object)
     */
    public final List getAllValues()
    {
        return Collections.unmodifiableList(_values);
    }

    /**
     * Returns a list of all values stored into the converter, with deleted values removed.
     */

    public final List getValues()
    {
        if (isDeletedValuesEmpty())
            return getAllValues();

        List result = new ArrayList(_values);

        result.removeAll(_deletedValues);

        return result;
    }

    /**
     * Returns true if the deleted values set is empty (or null).
     */
    private boolean isDeletedValuesEmpty()
    {
        return _deletedValues == null || _deletedValues.isEmpty();
    }

    /**
     * Checks to see if the {@link #getLastValue() last value} is, or is not, in the set of deleted
     * values.
     */
    public final boolean isDeleted()
    {
        return checkValueSetForLastValue(_deletedValues);
    }

    /**
     * Checks the set to see if it contains the {@link #getLastValue() last value}.
     * 
     * @param valueSet
     *            the set to check, which may be null
     * @return true if the last value is in the set (if non-null)
     */
    protected final boolean checkValueSetForLastValue(Set valueSet)
    {
        return valueSet != null && valueSet.contains(_lastValue);
    }

    /**
     * Adds or removes the {@link #getLastValue() last value} from the
     * {@link #getDeletedValues() deleted values set}.
     * 
     * @param deleted
     */
    public final void setDeleted(boolean deleted)
    {
        _deletedValues = updateValueSetForLastValue(_deletedValues, deleted);
    }

    /**
     * Updates a value set to add or remove the {@link #getLastValue() last value} to the set. The
     * logic here will create and return a new Set instance if necessary (that is, if inSet is true
     * and set is null). The point is to defer the creation of the set until its actually needed.
     * 
     * @param set
     *            the set to update, which may be null
     * @param inSet
     *            if true, the last value will be added to the set (creating the set as necessary);
     *            if false, the last value will be removed
     * @return the set passed in, or a new Set instance
     */
    protected final Set updateValueSetForLastValue(Set set, boolean inSet)
    {
        Set updatedSet = set;
        if (inSet)
        {
            if (updatedSet == null)
                updatedSet = new HashSet();

            updatedSet.add(_lastValue);

            return updatedSet;
        }

        if (updatedSet != null)
            updatedSet.remove(_lastValue);

        return updatedSet;
    }

    /**
     * Returns the last active value; this is the value passed to {@link #getPrimaryKey(Object)} or
     * the value for the key passed to {@link #getValue(Object)}.
     * <p>
     * Maintaining <em>value sets</em> involves adding or removing the active value from a set.
     * 
     * @return the last active object
     */
    public final Object getLastValue()
    {
        return _lastValue;
    }

    /**
     * Returns an unmodifiable set of all values marked as deleted.
     */

    public final Set getDeletedValues()
    {
        return createUnmodifiableSet(_deletedValues);
    }

    /**
     * Converts a value set into a returnable value; null is converted to the empty set, and
     * non-null is wrapped as unmodifiable.
     * 
     * @param valueSet
     *            the set to convert and return
     * @return a non-null, non-modifiable Set
     */
    protected final Set createUnmodifiableSet(Set valueSet)
    {
        return valueSet == null ? Collections.EMPTY_SET : Collections.unmodifiableSet(valueSet);
    }

    /**
     * Iterates over the keys and values, removing any values (and corresponding keys) that that are
     * in the deleted set. After invoking this, {@link #getAllValues()} will be the same as
     * {@link #getValues()}.
     */
    public final void removeDeletedValues()
    {
        _lastValue = null;

        if (isDeletedValuesEmpty())
            return;

        int count = _keys.size();

        for (int i = count - 1; i >= 0; i--)
        {
            if (_deletedValues.contains(_values.get(i)))
            {
                _values.remove(i);
                Object key = _keys.remove(i);

                _map.remove(key);
            }
        }
    }

    /**
     * Gets the primary key of an object previously stored in this converter.
     * 
     * @param value
     *            an object previously stored in the converter
     * @return the corresponding key used to store the object
     * @throws ApplicationRuntimeException
     *             if the value was not previously stored
     * @see #add(Object, Object)
     */
    public final Object getPrimaryKey(Object value)
    {
        int index = _values.indexOf(value);

        if (index < 0)
            throw new ApplicationRuntimeException(UtilMessages.valueNotFound(value), value, null,
                    null);

        _lastValue = value;

        return _keys.get(index);
    }

    /**
     * Given a primary key, locates the corresponding object. May invoke
     * {@link #provideMissingValue(Object)} if no such key has been stored into the converter.
     * 
     * @return the object if the key is found, or null otherwise.
     * @see #add(Object, Object)
     */
    public final Object getValue(Object primaryKey)
    {
        Object result = _map.get(primaryKey);

        if (result == null)
            result = provideMissingValue(primaryKey);

        _lastValue = result;

        return result;
    }

    /**
     * Invoked by {@link #getValue(Object)} when the key is not found in the converter's map.
     * Subclasses may override this method to either obtain the corresponding object from secondary
     * storage, to throw an exception, or to provide a new object instance. This implementation
     * returns null.
     * 
     * @param key
     *            the key for which an object was requested
     * @return the object for the key, or null if no object may can be provided
     */
    protected Object provideMissingValue(Object key)
    {
        return null;
    }

}