// **********************************************************************
//
// Copyright (c) 2002
// IONA Technologies, Inc.
// Waltham, MA, USA
//
// All Rights Reserved
//
// **********************************************************************

#ifndef OB_URL_IDL
#define OB_URL_IDL

#pragma prefix "ooc.com"

#include <OB/IOP.idl>

module OB
{

local interface URLScheme;

/**
 *
 * The URLRegistry holds all of the supported URL schemes.
 *
 * @see URLScheme
 *
 **/

local interface URLRegistry
{
    /** Another scheme already exists with the same name. */
    exception SchemeAlreadyExists {};

    /**
     *
     * Register a new URL scheme.
     *
     * @param scheme The new scheme.
     *
     * @exception SchemeAlreadyExists Another scheme already exists with
     * the same name.
     *
     **/

    void add_scheme(in URLScheme scheme)
        raises(SchemeAlreadyExists);

    /**
     *
     * Find a scheme with the given name.
     *
     * @param name The scheme name, in lower case.
     *
     * @return The URLScheme, or nil if no match was found.
     *
     **/

    URLScheme find_scheme(in string name);

    /**
     *
     * Convert a URL into an object reference by delegating to a
     * registered URLScheme object.
     *
     * @param url The complete URL, including the scheme.
     *
     * @return An object reference.
     *
     * @exception BAD_PARAM In case the URL is invalid.
     *
     **/

    Object parse_url(in string url);

    /**
     *
     * Invoke <code>destroy()</code> on all registered schemes, and
     * release any resources held by the object.
     *
     **/

    void destroy();
};

/**
 *
 * A URLScheme (e.g., <code>file:</code>, <code>corbaloc:</code>, etc.)
 * is responsible for converting a URL into an object reference.
 * All schemes must be installed in the <code>URLRegistry</code>.
 *
 * @see URLRegistry
 *
 **/

local interface URLScheme
{
    /**
     *
     * Each scheme must have a unique name. All scheme names must
     * be in lower case, and do not include the trailing colon.
     *
     **/

    readonly attribute string name;

    /**
     *
     * Convert a URL into an object reference.
     *
     * @param url The complete URL, including the scheme.
     *
     * @return An object reference.
     *
     * @exception BAD_PARAM In case the URL is invalid.
     *
     **/

    Object parse_url(in string url);

    /**
     *
     * Release any resources held by the object.
     *
     **/

    void destroy();
};

local interface CorbalocProtocol;

/**
 *
 * CorbalocURLScheme implements the <code>corbaloc</code> URL scheme,
 * and serves as a registry for CorbalocProtocol objects.
 *
 * @see CorbalocProtocol
 *
 **/

local interface CorbalocURLScheme : URLScheme
{
    /** Another protocol already exists with the same name. */
    exception ProtocolAlreadyExists {};

    /**
     *
     * Register a new <code>corbaloc</code> protocol.
     *
     * @param protocol The new protocol.
     *
     * @exception ProtocolAlreadyExists Another protocol already exists
     * with the same name.
     *
     **/

    void add_protocol(in CorbalocProtocol protocol)
        raises(ProtocolAlreadyExists);

    /**
     *
     * Find a protocol with the given name.
     *
     * @param name The protocol name, in lower case.
     *
     * @return The CorbalocProtocol, or nil if no match was found.
     *
     **/

    CorbalocProtocol find_protocol(in string name);
};

/**
 *
 * The <code>corbaloc</code> URL scheme supports multiple protocols,
 * the most common of which is <code>iiop</code>. The CorbalocURLScheme
 * delegates the parsing of protocol address information to a
 * registered CorbalocProtocol object.
 *
 * @see CorbalocURLScheme
 *
 **/

local interface CorbalocProtocol
{
    /**
     *
     * Each protocol must have a unique name. All protocol names must
     * be in lower case.
     *
     **/

    readonly attribute string name;

    /** Alias for a sequence of octets. */
    typedef sequence<octet> ObjectKey;

    /**
     *
     * Parse a protocol address and create a tagged profile for inclusion
     * in an IOR.
     *
     * @param addr The protocol address, not including the protocol name
     * or trailing object key. For example, the URL
     * <code>corbaloc:iiop:1.2@localhost:5000/Key</code> would result in
     * an address argument of <code>1.2@localhost:5000</code>.
     *
     * @param key The object key from the URL, converted into a sequence
     * of octets.
     *
     * @return A tagged profile.
     *
     * @exception BAD_PARAM In case the address is invalid.
     *
     **/

    IOP::TaggedProfile parse_address(in string addr, in ObjectKey key);

    /**
     *
     * Release any resources held by the object.
     *
     **/

    void destroy();
};

}; // End of module OB

#endif
