path: root/src/com/memberwebs/ldapxml/LXSpecs.java

/*
 * Copyright (c) 2004, Nate Nielsen
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 *     * Redistributions of source code must retain the above
 *       copyright notice, this list of conditions and the
 *       following disclaimer.
 *     * Redistributions in binary form must reproduce the
 *       above copyright notice, this list of conditions and
 *       the following disclaimer in the documentation and/or
 *       other materials provided with the distribution.
 *     * The names of contributors to this software may not be
 *       used to endorse or promote products derived from this
 *       software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
 * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 * DAMAGE.
 *
 *
 * CONTRIBUTORS
 *  Nate Nielsen <nielsen@memberwebs.com>
 *
 */

package com.memberwebs.ldapxml;

import java.util.Map;

import com.memberwebs.ldapxml.map.*;

/**
 * Additional specifications for retrieving data from an
 * LDAP directory.
 *
 * @author nielsen@memberwebs.com
 * @version 0.5
 */
public class LXSpecs
{
    /**
     * Don't retrieve any sub entries.
     */
    public static final int DEPTH_BASE = 0;

    /**
     * Retrive only direct children of the referenced entry.
     */
    public static final int DEPTH_SINGLE = 1;

    /**
     * Retrieve all sub entries.
     */
    public static final int DEPTH_INFINITE = 0xFFFFFFFF;


    private static final String LANG = "lang-";
	private static final String FILTER_ALL = "(objectClass=*)";

    /**
     * Construct a new LXSpecs object.
     */
    public LXSpecs()
    {
        m_filter = FILTER_ALL;
        m_depth = DEPTH_BASE;
        m_sort = null;
        m_data = null;
        m_language = null;
        m_start = 0;
        m_limit = Integer.MAX_VALUE;
    }

    public final int getStart()
    {
        return m_start;
    }

    public final int getLimit()
    {
        return m_limit;
    }

    public final void setStart(int start)
    {
        m_start = start;
    }

    public final void setLimit(int limit)
    {
        m_limit = limit;
    }

    /**
     * Get preferred language.
     *
     * @return The language or null if none set.
     */
    public final String getLanguage()
    {
        return m_language;
    }

    /**
     * Set preferred language for LDAP retrieval.
     *
     * @param language The language or null for no preference.
     */
    public final void setLanguage(String language)
    {
        m_language = language;

        if(m_language != null && !m_language.startsWith(LANG))
            m_language = LANG + m_language;
    }

    /**
     * Returns the depth to which entries are recursively
     * retrieved from the LDAP directory.
     *
     * @return The depth.
     */
    public final int getDepth()
    {
        return m_depth;
    }

    /**
     * Sets the depth to which entries are recursively
     * retrieved from the LDAP directory.
     *
     * @return The depth.
     */
    public final void setDepth(int depth)
    {
        m_depth = depth;
    }

    /**
     * Gets the additional filter when searching for entries.
     *
     * @return The filter.
     */
    public final String getFilter()
    {
        return m_filter == null ? FILTER_ALL : m_filter;
    }

    /**
     * Gets the filter when searching for entries, combining it
     * with another filter.
     *
     * @param prevFilter The other filter.
     * @return The combined filter.
     */
    public final String getFilter(String prevFilter)
    {
        String filter = combineFilters(m_filter, prevFilter);
        return filter == null ? FILTER_ALL : filter;
    }

    /**
     * Set an additional filter used when searching for entries.
     *
     * @param filter The filter.
     */
    public final void setFilter(String filter)
    {
        m_filter = combineFilters(filter, null);
    }

    /**
     * Get the requested sort order.
     *
     * @return The sort order, or null if none present.
     */
    public final String[] getSort()
    {
        if(m_sort != null && m_sort.length > 0)
            return m_sort;
        else
            return null;
    }

    /**
     * Get the sort directions (ascending, descending) for the
     * sort order.
     *
     * @return An array of sort directions.
     */
    public final boolean[] getSortDirection()
    {
        if(m_direc != null && m_direc.length > 0)
            return m_direc;
        else
            return null;
    }

    /**
     * Set the sort order. Attribute names prefixed with '-' are
     * treated as descending.
     *
     * @param sort The sort order.
     */
    public final void setSort(String[] sort)
    {
        m_mappedSort = null;

        m_sort = new String[sort.length];
        m_direc = new boolean[sort.length];

        for(int i = 0; i < sort.length; i++)
        {
            boolean desc = sort[i].startsWith("-");
            if(desc)
                m_sort[i] = sort[i].substring(1);
            else
                m_sort[i] = sort[i];

            m_direc[i] = !desc;
        }
    }

    public final Object getData()
    {
        return m_data;
    }

    public final void setData(Object data)
    {
        m_data = data;
    }

    /**
     * Translate the sort order with mapped LDAP attribute
     * names retrieved from the map.
     *
     * @param map The LX Map to get the attribute names from.
     * @return The translated sort order.
     */
    protected final String[] getMappedSort(LXMap map)
    {
        if(m_mappedSort == null)
        {
            if(m_sort != null && m_sort.length > 0)
            {
                m_mappedSort = new String[m_sort.length];

                Map nameMap = map.getNameMap();
                for(int i = 0; i < m_sort.length; i++)
                {
                    String name = (String)nameMap.get(m_sort[i]);
                    m_mappedSort[i] = name == null ? m_sort[i] : name;
                }
            }
        }
        return m_mappedSort;
    }

	/**
	 * Combine two LDAP filters in an AND operation.
	 *
	 * @param filter1 The first filter to combine.
	 * @param filter2 The second filter.
	 * @return The combined filter.
	 */
	protected static String combineFilters(String filter1, String filter2)
	{
		return combineFilters(filter1, filter2, '&');
	}

	/**
	 * Combine two LDAP filters in a boolean operation.
	 *
	 * @param filter1 The first filter to combine.
	 * @param filter2 The second filter.
	 * @param op The boolean operation (ie: '&' or '|' etc...)
	 * @return The combined filter.
	 */
	protected static String combineFilters(String filter1, String filter2, char op)
	{
		String filter = null;

		filter1 = cleanFilter(filter1);
		filter2 = cleanFilter(filter2);

		if(filter1 != null)
			filter = filter1;

		if(filter2 != null)
		{
			if(filter == null)
				filter = filter2;
			else
				filter = "("  + op + filter + filter2 + ")";
		}

		return filter;
	}

	/**
	 * Clean up an LDAP filter, substituting null for an empty,
	 * or all encompasing filter. Also wraps filters in parens
	 * as need.
	 *
	 * @param filter The filter to check.
	 * @return The new filter or null.
	 */
	protected static String cleanFilter(String filter)
	{
		if(filter != null)
		{
			if(!filter.startsWith("("))
				filter = "(" + filter + ")";

			if(filter.equals(""))
				filter = null;
			else if(filter.equals(FILTER_ALL))
				filter = null;
		}

		return filter;
	}

    // The additional filter
    private String m_filter;

    // The depth to which to recursively retrieve sub entries
    private int m_depth;

    // The starting point to retrieve entries
    private int m_start;
    // The number of entries to retrieve
    private int m_limit;

    // The sort order and direction
    private String[] m_sort;
    private String[] m_mappedSort;
    private boolean[] m_direc;

    // The preferred language
    private String m_language;

    // Data for hooks
    private Object m_data;
}