javax.tv.locator.LocatorFactory Maven / Gradle / Ivy

/**
This is not an official specification document, and usage is restricted.


NOTICE





(c) 2005-2008 Sun Microsystems, Inc. All Rights Reserved.


Neither this file nor any files generated from it describe a complete
specification, and they may only be used as described below.  

Sun Microsystems Inc. owns the copyright in this file and it is provided
to you for informative use only. For example, 
this file and any files generated from it may be used to generate other documentation, 
such as a unified set of documents of API signatures for a platform 
that includes technologies expressed as Java APIs. 
This file may also be used to produce "compilation stubs," 
which allow applications to be compiled and validated for such platforms. 
By contrast, no permission is given for you to incorporate this file, 
in whole or in part, in an implementation of a Java specification.

Any work generated from this file, such as unified javadocs or compiled
stub files, must be accompanied by this notice in its entirety.

This work corresponds to the API signatures of JSR 927: Java TV API 1.1.1.  
In the event of a discrepency between this work and the JSR 927 specification, 
which is available at http://www.jcp.org/en/jsr/detail?id=927, the latter takes precedence.
*/



  


package javax.tv.locator;

/** 
 * This class defines a factory for the creation of
 * Locator objects.
 *
 * @see javax.tv.locator.Locator 
 */
public abstract class LocatorFactory
{

    /** 
     * Creates the LocatorFactory instance.
     */
    protected LocatorFactory() { }

    /** 
     * Provides an instance of LocatorFactory.
     * 
     * @return A LocatorFactory instance.
     */
    public static LocatorFactory getInstance() {
        return null;
    }

    /** 
     * Creates a Locator object from the specified locator
     * string.  The format of the locator string may be entirely
     * implementation-specific.
     *
     * @param locatorString The string form of the Locator
     * to be created.
     *
     * @return A Locator object representing the resource
     * referenced by the given locator string.
     *
     * @throws MalformedLocatorException If an incorrectly formatted
     * locator string is detected.
     *
     * @see Locator#toExternalForm 
     */
    public abstract Locator createLocator(String locatorString)
        throws MalformedLocatorException;

    /** 
     * Transforms a Locator into its respective collection
     * of transport dependent Locator objects. A
     * transformation on a transport dependent Locator
     * results in an identity transformation, i.e. the same locator is
     * returned in a single-element array.
     *
     * @param source The Locator to transform.
     *
     * @return An array of transport dependent Locator
     * objects for the given Locator.
     * 
     * @throws InvalidLocatorException If source is not a valid
     * Locator.  
     */
    public abstract Locator[] transformLocator(Locator source)
        throws InvalidLocatorException;
}