framework/src/org/apache/click/Stateful.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.click;

/**
 * Provides an interface that controls can implement that need to preserve
 * state across multiple requests.
 * <p/>
 * <b>Please note:</b> Control state is not saved and restored automatically by
 * Click. Instead, state saving and restoring is under full control of the
 * developer through a public API.
 * <p/>
 * Controls implementing this interface are expected to {@link #getState() save}
 * and {@link #setState(java.lang.Object) restore} their internal state, as well
 * as the state of their child controls. Controls can further expose a public
 * API for saving and restoring their state.
 * <p/>
 * An example implementation is shown below:
 *
 * <pre class="prettyprint">
 * public class MyControl extends AbstractControl implements Stateful {
 *
 *     private String value;
 *
 *     ...
 *
 *     // Return the Control internal state
 *     public Object getState() {
 *         return getValue();
 *     }
 *
 *     // Set the Control internal state
 *     public void setState(Object state) {
 *         String fieldState = (String) state;
 *         setValue(fieldState);
 *     }
 *
 *    // A save state helper method
 *     public void saveState(Context context) {
 *         // Save the control state in the session
 *         ClickUtils.saveState(this, getName(), context);
 *     }
 *    // A restore state helper method
 *     public void restoreState(Context context) {
 *         // Load the control state from the session
           ClickUtils.restoreState(this, getName(), context);
 *     }
 *
 *    // A remove state helper method
 *     public void removeState(Context context) {
 *         // Remove the control state from the session
*          ClickUtils.removeState(this, getName(), context);
 *     }
 *
 * } </pre>
 *
 * Saving and restoring Control state is controlled by the developer.
 * <p/>
 * For example:
 *
 * <pre class="prettyprint">
 * public class MyPage extends Page {
 *
 *    private MyControl control = new MyControl("mycontrol");
 *
 *     public MyPage() {
 *         // Load the control state from the session
 *         control.loadState(getContext());
 *     }
 *
 *     public void onPost() {
 *
 *         Context context = getContext();
 *
 *         String id = context.getParameter("id");
 *         control.setValue(id);
 *
 *         // Save control state to the session
 *         control.saveState(context);
 *     }
 * }
 * </pre>
 */
public interface Stateful {

    /**
     * Return the Control internal state. State will generally be stored in the
     * Session, so it is recommended to ensure the state is
     * {@link java.io.Serializable serializable}.
     * <p/>
     * Example implementation below:
     * <pre class="prettyprint">
     * public Object getState() {
     *     Object stateArray[] = new Object[3];
     *     stateArray[0] = getValue();
     *     stateArray[1] = Number.valueOf(getNumber());
     *     stateArray[2] = Boolean.valueOf(getBoolean());
     *     return stateArray;
     * } </pre>
     *
     * @return the control internal state
     */
    public Object getState();

    /**
     * Restore the Control internal state from the given state object.
     * <p/>
     * Example below:
     * <pre class="prettyprint">
     * public void setState(Object state) {
     *
     *     Object[] stateArray = (Object[]) state;
     *     String storedValue = stateArray[0];
     *     setValue(storedValue);
     *
     *     int storedNumber = ((Integer) stateArray[1]).intValue();
     *     setNumber(storedNumber);
     *
     *     boolean storedBoolen = ((Boolean) stateArray[2]).booleanValue();
     *     setBoolean(storedBoolean);
     * } </pre>
     *
     * @param state the control state to restore
     */
    public void setState(Object state);
}