2362N/A * Copyright (c) 2000, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * An interface to be implemented by objects that can determine the 0N/A * settings of an <code>IIOParam</code> object, either by putting up a 0N/A * GUI to obtain values from a user, or by other means. This 0N/A * interface merely specifies a generic <code>activate</code> method 0N/A * that invokes the controller, without regard for how the controller 0N/A * obtains values (<i>i.e.</i>, whether the controller puts up a GUI 0N/A * or merely computes a set of values is irrelevant to this 0N/A * <p> Within the <code>activate</code> method, a controller obtains 0N/A * initial values by querying the <code>IIOParam</code> object's 0N/A * <code>get</code> methods, modifies values by whatever means, then 0N/A * invokes the <code>IIOParam</code> object's <code>set</code> methods 0N/A * to modify the appropriate settings. Normally, these 0N/A * <code>set</code> methods will be invoked all at once at a final 0N/A * commit in order that a cancel operation not disturb existing 0N/A * values. In general, applications may expect that when the 0N/A * <code>activate</code> method returns <code>true</code>, the 0N/A * <code>IIOParam</code> object is ready for use in a read or write 0N/A * <p> Vendors may choose to provide GUIs for the 0N/A * <code>IIOParam</code> subclasses they define for a particular 0N/A * plug-in. These can be set up as default controllers in the 0N/A * corresponding <code>IIOParam</code> subclasses. 0N/A * <p> Applications may override any default GUIs and provide their 0N/A * own controllers embedded in their own framework. All that is 0N/A * required is that the<code>activate</code> method behave modally 0N/A * (not returning until either cancelled or committed), though it need 0N/A * not put up an explicitly modal dialog. Such a non-modal GUI 0N/A * component would be coded roughly as follows: 0N/A * class MyGUI extends SomeComponent implements IIOParamController { 0N/A * setEnabled(false); 0N/A * public boolean activate(IIOParam param) { 0N/A * // disable other components if desired 0N/A * // go to sleep until either cancelled or committed 0N/A * boolean ret = false; 0N/A * // set values on param 0N/A * setEnabled(false); 0N/A * // enable any components disabled above 0N/A * <p> Alternatively, an algorithmic process such as a database lookup 0N/A * or the parsing of a command line could be used as a controller, in 0N/A * which case the <code>activate</code> method would simply look up or 0N/A * compute the settings, call the <code>IIOParam.setXXX</code> 0N/A * methods, and return <code>true</code>. 0N/A * @see IIOParam#setController 0N/A * @see IIOParam#getController 0N/A * @see IIOParam#getDefaultController 0N/A * @see IIOParam#hasController 0N/A * @see IIOParam#activateController 0N/A * Activates the controller. If <code>true</code> is returned, 0N/A * all settings in the <code>IIOParam</code> object should be 0N/A * ready for use in a read or write operation. If 0N/A * <code>false</code> is returned, no settings in the 0N/A * <code>IIOParam</code> object will be disturbed (<i>i.e.</i>, 0N/A * the user canceled the operation). 0N/A * @param param the <code>IIOParam</code> object to be modified. 0N/A * @return <code>true</code> if the <code>IIOParam</code> has been 0N/A * modified, <code>false</code> otherwise. 0N/A * @exception IllegalArgumentException if <code>param</code> is 0N/A * <code>null</code> or is not an instance of the correct class.