net.agmodel.genericBroker
Interface GenericBrokerRMI

All Superinterfaces:

Remote, ServerRMI

All Known Subinterfaces:

ChizuBroker, DEMBroker, MetBroker

All Known Implementing Classes:

GenericBrokerImpl

public interface GenericBrokerRMI

extends ServerRMI

An extension of ServerRMI which adds the functionality common to all brokers (a broker provides a consistent interface to multiple databases).
The common functionality includes getting lists of linked databases, and logging the user into and out of a particular database.
Typically a client establishes a Broker session through a call to ServerRMI.getConnection(String,String).
The sessionID received back is used to identify the user subsequently.

Field Summary

static int	EMAIL The database requires the users e-mail address (eg for anonymous FTP)
static String	HOSTPARAMEXTENSION The extension used by subclasses when generating the name of the parameter for the RMI host name
static int	NOLOGIN The database (typically a web site) doesn't require any user details for accesss
static int	PASSWORD The database requires a user code and password

Fields inherited from interface net.agmodel.genericBroker.ServerRMI

EXISTINGUSER, NEWUSER, SUPERUSER

Method Summary

boolean	alreadyLoggedIn(String sessionID, String sourceID) Check whether any required connection to the specified database has already been established.
DataSourceDetail	getSourceDetail(String sessionID, String dataSourceID) Gets details about a single data source.
String	getSourceID(String sessionID, String language, String sourceName) Get the ID of a data source using its name in a particular language.
DataSourceDetail[]	listSourceDetails(String sessionID) Get the details for all the data sources in the broker.
DataSourceDetail[]	listSourceDetails(String sessionID, GeographicalArea ofInterest) Get the details of the data sources in the broker that coincide with the area specified.
boolean	loginToDataSource(String sessionID, String sourceID) Establish a connection to the specified database without identifying the user in any way
boolean	loginToDataSource(String sessionID, String sourceID, String emailAddress) Establish a connection to the specified database using the e-mail address supplied as identification.
boolean	loginToDataSource(String sessionID, String sourceID, String usercode, String password) Establish a connection to the specified database using the usercode and password supplied
void	logOutOfAllSources(String sessionID) Log out from any data sources to which the client is currently logged in.
void	logOutOfSource(String sessionID, String sourceID) Log out from the data source identified by the sourceID

Methods inherited from interface net.agmodel.genericBroker.ServerRMI

disconnect, getConnection, getConnection

Field Detail

NOLOGIN

public static final int NOLOGIN

The database (typically a web site) doesn't require any user details for accesss

See Also:

Constant Field Values

EMAIL

public static final int EMAIL

The database requires the users e-mail address (eg for anonymous FTP)

See Also:

Constant Field Values

PASSWORD

public static final int PASSWORD

The database requires a user code and password

See Also:

Constant Field Values

HOSTPARAMEXTENSION

public static final String HOSTPARAMEXTENSION

The extension used by subclasses when generating the name of the parameter for the RMI host name

See Also:

Constant Field Values

Method Detail

listSourceDetails

public DataSourceDetail[] listSourceDetails(String sessionID)
                                     throws RemoteException,
                                            GeneralException

Get the details for all the data sources in the broker.

Parameters:

sessionID - the ID returned by getConnection

Returns:

a list of sources

RemoteException

GeneralException

listSourceDetails

public DataSourceDetail[] listSourceDetails(String sessionID,
                                            GeographicalArea ofInterest)
                                     throws RemoteException,
                                            GeneralException

Get the details of the data sources in the broker that coincide with the area specified.

Parameters:

sessionID - the ID returned by getConnection

ofInterest - the area from which data is required

Returns:

a list of sources whose GeographicalAreas overlap with the area of Interest

RemoteException

GeneralException

getSourceDetail

public DataSourceDetail getSourceDetail(String sessionID,
                                        String dataSourceID)
                                 throws RemoteException

Gets details about a single data source.

Parameters:

sessionID - the ID returned by getConnection

Returns:

the database details

Throws:

IllegalArgumentException - if the data source ID is not known

RemoteException

getSourceID

public String getSourceID(String sessionID,
                          String language,
                          String sourceName)
                   throws RemoteException,
                          GeneralException

Get the ID of a data source using its name in a particular language. This ID is not intended for presentation to users - use getName instead.

Parameters:

sessionID - the ID returned by getConnection

sourceName - the name of the source (in the language specified)

language - the language of the name using ISO standard language codes

Returns:

the ID of the requested source, or null if it cannot be located

RemoteException

GeneralException

loginToDataSource

public boolean loginToDataSource(String sessionID,
                                 String sourceID,
                                 String usercode,
                                 String password)
                          throws RemoteException,
                                 GeneralException

Establish a connection to the specified database using the usercode and password supplied

Parameters:

sessionID - the ID returned by getConnection

sourceID - the identifier assigned to the source by the broker - see listSourceDetails

usercode - a valid usercode on the source

password - the corresponding password (warning - may be transmitted without encryption)

Returns:

true if the the broker was able to log in to the source, false otherwise

RemoteException

GeneralException

See Also:

getSourceDetail(String,String)

loginToDataSource

public boolean loginToDataSource(String sessionID,
                                 String sourceID,
                                 String emailAddress)
                          throws RemoteException,
                                 GeneralException

Establish a connection to the specified database using the e-mail address supplied as identification.

Parameters:

sessionID - the ID returned by getConnection

sourceID - the identifier assigned to the source by the broker - see listSourceDetails

emailAddress - the user's e-mail address

Returns:

true if the broker was able to log in to the source, false otherwise

RemoteException

GeneralException

See Also:

getSourceDetail(String,String)

loginToDataSource

public boolean loginToDataSource(String sessionID,
                                 String sourceID)
                          throws RemoteException,
                                 GeneralException

Establish a connection to the specified database without identifying the user in any way

Parameters:

sessionID - the ID returned by getConnection

sourceID - the identifier assigned to the source by the broker - see listSourceDetails

Returns:

true if the the broker was able to log in to the source, false otherwise

RemoteException

GeneralException

See Also:

getSourceDetail(String,String)

alreadyLoggedIn

public boolean alreadyLoggedIn(String sessionID,
                               String sourceID)
                        throws RemoteException

Check whether any required connection to the specified database has already been established.

Parameters:

sessionID - the ID returned by getConnection

sourceID - the identifier assigned to the source by the broker - see listSourceDetails

Returns:

true if the broker is able to proceed with data access, false if a required connection needs to be established.

RemoteException

logOutOfSource

public void logOutOfSource(String sessionID,
                           String sourceID)
                    throws RemoteException

Log out from the data source identified by the sourceID

Parameters:

sessionID - the ID returned by getConnection

sourceID - the identifier assigned to the source by the broker

RemoteException

logOutOfAllSources

public void logOutOfAllSources(String sessionID)
                        throws RemoteException

Log out from any data sources to which the client is currently logged in.

Parameters:

sessionID - the ID returned by getConnection

RemoteException