/*
 * 
 * Copyright 2004 Sun Microsystems, Inc. All Rights Reserved.
 * 
 * The contents of this file are subject to the Sun Community Source
 * License v3.0/Jini Technology Specific Attachment v 1.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://wwws.sun.com/software/jini/licensing/SCSL3_JiniTSA1.html.
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 * 
 * The Reference Code is Jini Technology Core Platform code, v2.0. The
 * Developer of the Reference Code is Sun Microsystems, Inc.
 * 
 * Contributor(s): Sun Microsystems, Inc.
 * 
 * The contents of this file comply with the Jini Technology Core
 * Platform Compatibility Kit, v2.0A.
 * 
 * Tester(s): Sun Microsystems, Inc.
 * 
 * Test Platform(s):
 * Java 2 SDK, Standard Edition, Version 1.4.2_03 for Solaris(TM)SPARC/x86
 * Java 2 SDK, Standard Edition, Version 1.4.2_03 for Linux (Intel x86)
 * Java 2 SDK, Standard Edition, Version 1.4.2_03 for Windows (Intel Platform)
 * 
 */

package net.jini.lookup;

import java.rmi.RemoteException;
import java.io.IOException;

/**
 * Methods for controlling which groups a lookup service is a member of,
 * and for controlling which TCP port a lookup service uses for its
 * lookup locator.  Lookup services that implement the Administrable
 * interface should return an admin object that implements this interface.
 * 
 * @author Sun Microsystems, Inc.
 */
public interface DiscoveryAdmin {

    /**
     * Returns an array consisting of the names of the groups in which the
     * lookup service is a member. If the lookup service currently belongs
     * to no groups, this method will return the empty array.
     *
     * @return <code>String</code> array consisting of the names of the groups
     *         in which the lookup service is a member
     * 
     * @throws java.rmi.RemoteException typically, this exception occurs when
     *         there is a communication failure between the client and the
     *         server.
     */
    String[] getMemberGroups() throws RemoteException;

    /**
     * Adds the given set of names to the set whose elements are the names
     * of the groups in which the lookup service is currently a member.
     * Elements in the input set that duplicate names of groups in which
     * the lookup service is already a member will be ignored. If the empty
     * array (<code>NO_GROUPS</code>) is input, this method takes no action.
     *
     * @param groups <code>String</code> array consisting of the names of
     *               the new, additional groups in which the lookup service
     *               is to be a member.
     *
     * @throws java.rmi.RemoteException typically, this exception occurs when
     *         there is a communication failure between the client and the
     *         server.
     *
     * @throws java.lang.NullPointerException this exception occurs when
     *         either <code>null</code> is input to the <code>groups</code>
     *         parameter, or one or more of the elements of the
     *         <code>groups</code> parameter is <code>null</code>.
     */
    void addMemberGroups(String[] groups) throws RemoteException;

    /**
     * Deletes the elements of the given set of names from the set whose
     * elements are the names of the groups in which the lookup service is
     * currently a member. Any element in the input set that is not a name
     * of a group in which the lookup service is currently a member will be
     * ignored. If the empty array (<code>NO_GROUPS</code>) is input, this
     * method takes no action.
     *
     * @param groups <code>String</code> array consisting of the names to 
     *               remove from the set whose elements are the names of the
     *               groups in which the lookup service is currently a member.
     *
     * @throws java.rmi.RemoteException typically, this exception occurs when
     *         there is a communication failure between the client and the
     *         server.
     *
     * @throws java.lang.NullPointerException this exception occurs when
     *         either <code>null</code> is input to the <code>groups</code>
     *         parameter, or one or more of the elements of the
     *         <code>groups</code> parameter is <code>null</code>.
     */
    void removeMemberGroups(String[] groups) throws RemoteException;

    /**
     * Replaces the set whose elements are the names of the groups in which
     * the lookup service is currently a member with the given set of group
     * names. Elements in the input set that duplicate other elements in the
     * input set will be ignored. If the empty array (<code>NO_GROUPS</code>)
     * is input, then the lookup service will be a member of no groups.
     *
     * @param groups <code>String</code> array consisting of the names of
     *               the new groups in which the lookup service is to be a
     *               member.
     *
     * @throws java.rmi.RemoteException typically, this exception occurs when
     *         there is a communication failure between the client and the
     *         server.
     *
     * @throws java.lang.NullPointerException this exception occurs when
     *         either <code>null</code> is input to the <code>groups</code>
     *         parameter, or one or more of the elements of the
     *         <code>groups</code> parameter is <code>null</code>.
     */
    void setMemberGroups(String[] groups) throws RemoteException;

    /**
     * Returns the port number on which the lookup service listens for
     * unicast discovery queries.
     *
     * @return an <code>int</code> representing the port number on which the
     *         lookup service listens for unicast discovery queries.
     * 
     * @throws java.rmi.RemoteException typically, this exception occurs when
     *         there is a communication failure between the client and the
     *         server.
     */
    public int getUnicastPort() throws RemoteException;

    /**
     * Changes the number of the port on which the lookup service is currently
     * listening for unicast discovery queries to the given port number.
     * If a value of zero is input, then the lookup service will first try
     * to listen on the standard unicast discovery port, but if that fails,
     * the lookup service will listen on an arbitrary port.
     *
     * @param port <code>int</code> representing the new port number on which
     *             the lookup service should listen for unicast discovery
     *             queries.
     *
     * @throws java.io.IOException because an invocation of this method will
     *         result in the re-initiation of the unicast discovery process,
     *         which can throw an <code>IOException</code> when socket
     *         allocation occurs.
     * 
     * @throws java.rmi.RemoteException typically, this exception occurs when
     *         there is a communication failure between the client and the
     *         server.
     */
    public void setUnicastPort(int port) throws IOException, RemoteException;
}
