/*

 * CDDL HEADER START

 *

 * The contents of this file are subject to the terms of the

 * Common Development and Distribution License (the "License").

 * You may not use this file except in compliance with the License.

 *

 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

 * or http://www.opensolaris.org/os/licensing.

 * See the License for the specific language governing permissions

 * and limitations under the License.

 *

 * When distributing Covered Code, include this CDDL HEADER in each

 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.

 * If applicable, add the following below this CDDL HEADER, with the

 * fields enclosed by brackets "[]" replaced with your own identifying

 * information: Portions Copyright [yyyy] [name of copyright owner]

 *

 * CDDL HEADER END

 */

/*

 * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.

 * Use is subject to license terms.

 */

package org.opensolaris.os.vp.panel.common.control;

import java.io.UnsupportedEncodingException;

import java.net.*;

import java.util.*;

import org.opensolaris.os.vp.panel.common.action.*;

/**

 * The {@code Control} class encapsulates the control over all aspects of a

 * single point in a navigation hierarchy.

 */

public abstract class Control implements Navigable, HasControl {

    //

    // Static data

    //

    private static final String ENCODING = "UTF-8";

    //

    // Instance data

    //

    private Navigator navigator;

    private String id;

    private String name;

    private Map<String, String> parameters;

    private StructuredAction<?, ?, ?> resetAction =

	new StructuredAction<Object, Object, Object>(null) {

	    @Override

	    public Object work(Object pInput, Object rtInput)

		throws ActionAbortedException, ActionFailedException {

		reset();

		return null;

	    }

	};

    private StructuredAction<?, ?, ?> saveAction =

	new StructuredAction<Object, Object, Object>(null) {

	    @Override

	    public Object work(Object pInput, Object rtInput)

		throws ActionAbortedException, ActionFailedException {

		try {

		    save();

		} catch (ActionUnauthorizedException e) {

		    throw new ActionFailedException(e);

		}

		return null;

	    }

	};

    //

    // Constructors

    //

    /**

     * Constructs a {@code Control} with the given identifier and name.

     */

    public Control(String id, String name) {

	setId(id);

	setName(name);

    }

    /**

     * Constructs a {@code Control} with a {@code null} identifier and name.

     */

    public Control() {

	this(null, null);

    }

    //

    // HasId methods

    //

    /**

     * Gets an identifier for this {@code Control}, sufficiently unique as to

     * distinguish itself from its siblings.

     */

    @Override

    public String getId() {

	return id;

    }

    //

    // Navigable methods

    //

    /**

     * Gets the localized name of this {@code Control}.

     */

    @Override

    public String getName() {

	return name;

    }

    /**

     * Gets the initialization parameters passed to the {@link #start} method,

     * if this {@code Control} is started, or {@code null} if this {@code

     * Control} is stopped.

     */

    @Override

    public Map<String, String> getParameters() {

	return parameters;

    }

    //

    // HasControl methods

    //

    @Override

    public Control getControl() {

	return this;

    }

    //

    // Control methods

    //

    /**

     * Called by the {@link Navigator} just after a child {@code Control} of

     * this {@code Control} has been started and pushed onto the {@link

     * Navigator}'s {@code Control} stack.

     * <p>

     * This default implementation does nothing.

     *

     * @param	    control

     *		    the child {@code Control}

     */

    public void childStarted(Control control) {

    }

    /**

     * Called by the {@link Navigator} just after a child {@code Control} of

     * this {@code Control} has been stopped and popped off the {@link

     * Navigator}'s {@code Control} stack.

     * <p>

     * This default implementation does nothing.

     *

     * @param	    control

     *		    the child {@code Control}

     */

    public void childStopped(Control control) {

    }

    /**

     * Gets a list of {@code Navigable}s that resolve to a child {@code Control}

     * of this {@code Control}.

     *

     * @return	    a non-{@code null} (but possibly empty) {@code Collection}

     */

    public abstract List<Navigable> getBrowsable();

    /**

     * Gets a {@link StructuredAction} that invokes {@link #reset}.

     */

    public StructuredAction<?, ?, ?> getResetAction() {

	return resetAction;

    }

    /**

     * Gets a {@link StructuredAction} that invokes {@link #save}.

     */

    public StructuredAction<?, ?, ?> getSaveAction() {

	return saveAction;

    }

    /**

     * Gets a hint as to whether this {@code Control} should be returned by a

     * parent {@code Control}'s {@link #getBrowsable} method.  The parent may

     * choose to ignore this hint.

     */

    public abstract boolean isBrowsable();

    /**

     * Gets the child {@code Control} with the given identifier, creating it if

     * necessary.

     *

     * @param	    id

     *		    a unique identifier, as reported by the child {@code

     *		    Control}'s {@link #getId} method.

     *

     * @return	    a {@code Control} object, or {@code null} if no such child

     *		    is known

     */

    public abstract Control getChildControl(String id);

    /**

     * Gets a path to forward to automatically when this {@code Control} is the

     * final destination of the {@link Navigator}.  When this {@code Control} is

     * at the top of the {@code Control} stack (not in transit to another

     * {@code Control}), the {@link Navigator} will automatically navigate to

     * the returned path.

     * <p>

     * This default implementation returns {@code null}.

     *

     * @return	    an absolute or relative path, or {@code null} if no

     *		    automatic forwarding should occur

     */

    public String getForwardingPath() {

	return null;

    }

    /**

     * Gets the {@link Navigator} passed to the {@link #start} method, if

     * this {@code Control} is started, or {@code null} if this {@code Control}

     * is stopped.

     */

    public Navigator getNavigator() {

	return navigator;

    }

    protected boolean isStarted() {

	return navigator != null;

    }

    /**

     * If appropriate, resets this {@code Control}, discarding any pending

     * changes.

     * <p/>

     * This default implementation does nothing.

     *

     * @exception   ActionAbortedException

     *		    if this operation is cancelled

     *

     * @exception   ActionFailedException

     *		    if this operation fails

     */

    protected void reset() throws ActionAbortedException, ActionFailedException

    {

    }

    /**

     * If appropriate, saves any changes made while this {@code Control} is

     * running.

     * <p/>

     * This default implementation does nothing.

     *

     * @exception   ActionAbortedException

     *		    if this operation is cancelled

     *

     * @exception   ActionFailedException

     *		    if this operation fails

     *

     * @exception   ActionUnauthorizedException

     *		    if the current user has insufficient privileges for this

     *		    operation

     */

    protected void save() throws ActionAbortedException, ActionFailedException,

	ActionUnauthorizedException {

    }

    /**

     * Sets the identifier for this {@code Control}.

     */

    protected void setId(String id) {

	this.id = id;

    }

    /**

     * Sets the name for this {@code Control}.

     */

    protected void setName(String name) {

	this.name = name;

    }

    protected void setNavigator(Navigator navigator) {

	this.navigator = navigator;

    }

    private void setParameters(Map<String, String> parameters) {

	this.parameters = parameters;

    }

    /**

     * Called by the {@link Navigator} when this {@code Control} is pushed onto

     * the {@code Control} stack.

     * <p>

     * This default implementation saves references to the given {@link

     * #getNavigator Navigator} and {@link #getParameters initialization

     * parameters}.

     *

     * @param	    navigator

     *		    the {@link Navigator} that handles navigation to/from this

     *		    {@code Controls}

     *

     * @param	    parameters

     *		    non-{@code null}, but optional (may be empty) initialization

     *		    parameters

     *

     * @exception   NavigationAbortedException

     *		    if this {@code Control} could not be started due to the

     *		    action being cancelled or vetoed

     *

     * @exception   InvalidParameterException

     *		    if this {@code Control} could not be started due to invalid

     *		    intialization parameters

     */

    public void start(Navigator navigator, Map<String, String> parameters)

	throws NavigationAbortedException, InvalidParameterException {

	setNavigator(navigator);

	setParameters(parameters);

    }

    /**

     * Called by the {@link Navigator} prior to this {@code Control} being

     * removed as the current {@code Control}.

     * <p>

     * This default implementation resets the reference to the {@code

     * Navigator} and removes any set parameters.

     *

     * @exception   NavigationAbortedException

     *		    if this {@code Control} should remain the current {@code

     *		    Control}

     */

    public void stop() throws NavigationAbortedException {

	setNavigator(null);

	setParameters(null);

    }

    //

    // Static methods

    //

    /**

     * Encodes the given identifier and parameters.

     *

     * @param	    id

     *		    a {@link Control#getId Control identifier}

     *

     * @param	    parameters

     *		    initialization parameters, or {@code null} if no parameters

     *		    apply

     *

     * @return	    an encoded String

     */

    public static String encode(String id, Map<String, String> parameters) {

	StringBuffer buffer = new StringBuffer();

	try {

	    buffer.append(URLEncoder.encode(id, ENCODING));

	    if (parameters != null && !parameters.isEmpty()) {

		buffer.append("?");

		boolean first = true;

		for (String key : parameters.keySet()) {

		    if (first) {

			first = false;

		    } else {

			buffer.append("&");

		    }

		    String value = parameters.get(key);

		    if (value == null) {

			value = "";

		    } else {

			value = URLEncoder.encode(value, ENCODING);

		    }

		    key = URLEncoder.encode(key, ENCODING);

		    buffer.append(key).append("=").append(value);

		}

	    }

	} catch (UnsupportedEncodingException ignore) {

	}

	return buffer.toString();

    }

    public static SimpleNavigable decode(String encoded) {

	String[] elements = encoded.split("\\?", 2);

	String id = elements[0];

	Map<String, String> parameters = new HashMap<String, String>();

	try {

	    id = URLDecoder.decode(elements[0], ENCODING);

	} catch (UnsupportedEncodingException ignore) {

	}

	if (elements.length >= 2 && !elements[1].isEmpty()) {

	    String[] keyEqVals = elements[1].split("&");

	    for (String keyEqVal : keyEqVals) {

		String[] nvPair = keyEqVal.split("=", 2);

		String key = nvPair[0];

		String value = nvPair.length < 2 ? "" : nvPair[1];

		try {

		    key = URLDecoder.decode(key, ENCODING);

		    value = URLDecoder.decode(value, ENCODING);

		} catch (UnsupportedEncodingException ignore) {

		}

		parameters.put(key, value);

	    }

	}

	return new SimpleNavigable(id, parameters);

    }

}