/*
 * 
 * Copyright  1990-2009 Sun Microsystems, Inc. All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version
 * 2 only, as published by the Free Software Foundation.
 * 
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License version 2 for more details (a copy is
 * included at /legal/license.txt).
 * 
 * You should have received a copy of the GNU General Public License
 * version 2 along with this work; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 * 
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
 * Clara, CA 95054 or visit www.sun.com if you need additional
 * information or have any questions.
 */

package javax.microedition.media;

/**
 * <code>Controllable</code> provides an interface for
 * obtaining the <code>Control</code>s from an object 
 * like a <code>Player</code>.
 * It provides methods to query all the supported <code>Control</code>s
 * and to obtain a particular <code>Control</code> based on its class
 * name. 
 **/
public interface Controllable {

    /**
     * Obtain the collection of <code>Control</code>s
     * from the object that implements this interface.
     * <p>
     * Since a single object can implement multiple 
     * <code>Control</code> interfaces, it's necessary
     * to check each object against different <code>Control</code>
     * types.  For example:
     * <p>
     * <code>
     *   Controllable controllable;<br>
     *       :<br>
     *   Control cs[];<br>
     *   cs = controllable.getControls();<br>
     *   for (int i = 0; i < cs.length; i++) {<br>
     *       if (cs[i] instanceof ControlTypeA)<br>
     *           doSomethingA();<br>
     *       if (cs[i] instanceof ControlTypeB)<br>
     *           doSomethingB();<br>
     *       // etc. <br>
     *   }<br>
     * </code>
     * <p>
     * The list of <code>Control</code> objects returned
     * will not contain any duplicates.  And the list will not
     * change over time.
     * <p>
     * If no <code>Control</code> is supported, a zero length 
     * array is returned.
     *
     * @return the collection of <code>Control</code> objects.
     * @exception IllegalStateException Thrown if <code>getControls</code>
     * is called in a wrong state.
     * See 
     * <a href="Player.html#controls"><code>Player</code></a> 
     * and 
     * <a href="protocol/DataSource.html#controls"><code>DataSource</code></a> 
     * for more details.
     */
    Control[] getControls();

    /**
     * Obtain the object that implements the specified
     * <code>Control</code> interface.
     * <p>
     * If the specified <code>Control</code> interface is not supported 
     * then <code>null</code> is returned.
     * <p>
     * If the <code>Controllable</code> supports multiple objects that 
     * implement the same specified <code>Control</code> interface, only
     * one of them will be returned.  To obtain all the 
     * <code>Control</code>'s of that type, use the <code>getControls</code>
     * method and check the list for the requested type.
     *
     * @param controlType the class name of the <code>Control</code>.  
     * The class name
     * should be given either as the fully-qualified name of the class; 
     * or if the package of the class is not given, the package 
     * <code>javax.microedition.media.control</code> is assumed. 
     *
     * @return the object that implements the control,
     * or <code>null</code>.
     * @exception IllegalArgumentException Thrown if <code>controlType</code>
     * is <code>null</code>.
     * @exception IllegalStateException Thrown if <code>getControl</code>
     * is called in a wrong state.
     * See 
     * <a href="Player.html#controls"><code>Player</code></a> 
     * and 
     * <a href="protocol/DataSource.html#controls"><code>DataSource</code></a> 
     * for more details.
     */
    Control getControl(String controlType);
    
}