org.globus.mds
Class MDS

java.lang.Object
  |
  +--org.globus.mds.MDS

All Implemented Interfaces:

java.io.Serializable

public class MDS

extends java.lang.Object

implements java.io.Serializable

The interface to the Monitoring and Discovery Service.

USING THE MDS CLASS

The intention of the MDS class is to simplify the connection to the Monitoring and Discovery Service (MDS). This includes:

1. establishing a conection to an MDS Server,
2. quering for contents in the MDS,
3. printing the result of a query, and
4. disconecting from the MDS Server.

The main motivation for this class is to have an intermediate Application Layer which can be easily adapted to different LDAP client libraries (JNDI, Netscape SDK, Microsoft SDK). To adapt to the differnt API's only a limited number of routines have to be ported. The current release is based on JNDI.

Connecting

The first step in using the class is to establish a connection, which is done in the following way:

MDS mds = new MDS("www.globus.org", "389", "o=Globus, c=US");

The parameters to the mds class are simply the DNS name of the MDS server and the port number for the connection. The default values for the connection to the MDS are set to ldap://mds.globus.org:389, which are used in case no parameters are specified:

MDS mds = new MDS();

Searching

Searching the MDS is done with LDAP queries in respect to a base directory specified by a distingished name (DN). The top level of a globus related seraches is:

o=Globus, c=US

A search is invoked in the following way:

NamingEnumeration result;
result = mds.search("o=Globus, c=US", "(objectclass=*)", MDS.ONELEVEL_SCOPE);

The search result is stored in a NamingEnumeration as provided by JNDI.

Printing

A result from a search can be modified by the appropiate JNDI functions. A simple print function is provided which is intended to simplify debugging and programming development:

mds.print(result, false);

Example

The following example shows a program which connets to the MDS, and prints all ComputeResources located at Argonne National Laboratory:

MDS mds = new MDS("mds.globus.org", "389");
try {
mds.connect();
String bindDN =
"o=Argonne National Laboratory, o=Globus,c=US";
Vector result;
result = mds.search(bindDN,
"(objectclass=GlobusComputeResource)", MDS.ONELEVEL_SCOPE);
System.out.println(results);
mds.disconnect();
} catch(MDSException e) {
System.err.println( "Error:"+ e.getLdapMessage() );
}

See Also:

Serialized Form

Field Summary

protected javax.naming.ldap.LdapContext	ctx
protected static java.lang.String	DEFAULT_CTX
protected java.util.Properties	env
protected int	limit
static int	OBJECT_SCOPE
static int	ONELEVEL_SCOPE
static int	SUBTREE_SCOPE
protected int	timeout
protected int	version

Constructor Summary

MDS()
initilaizes a connetion to the MDS database with its default values

MDS(GlobusURL spec)
initilaizes a connetion to the MDS database using the specified LDAP URL

MDS(java.lang.String hostname, java.lang.String port)
initilaizes a connetion to the MDS database to the speified host and port

MDS(java.lang.String hostname, java.lang.String port, java.lang.String baseDN)
initilaizes a connetion to the MDS database to the speified host and port

Method Summary

void	addAttribute(java.lang.String dn, MDSResult at) adds attributes to an entry.
void	addEntry(java.lang.String dn, MDSResult at) adds attributes specified in a Attributes to an Object.
void	addPropertyChangeListener(java.beans.PropertyChangeListener l)
void	connect() connects to the specified server
void	connect(java.lang.String managerDN, java.lang.String password) connects and authenticates to the specified server
protected javax.naming.directory.SearchControls	createConstraints(int scope, java.lang.String[] attrToReturn)
void	deleteAttribute(java.lang.String dn, java.lang.String attr) deletes a specific attribute of an entry.
void	deleteEntry(java.lang.String dn) deletes a specific object specified by the dn.
void	deleteTree(java.lang.String dn, boolean deleteItSelf) deletes a subtree starting from dn
void	deleteValues(java.lang.String dn, MDSResult at) deletes attributes of an entry.
void	disconnect() disconnects from the MDS server
MDSResult	getAttributes(java.lang.String dn) This methods returns that attributes of the specified distinguished name.
MDSResult	getAttributes(java.lang.String dn, java.lang.String[] attributes) This methods returns that attributes of the specified distinguished name.
java.lang.String	getBaseDN() returns the baseDN currently used
java.lang.String	getHostname() gets the hostname
int	getLdapVersion() gets ldap protocol version
java.lang.String	getPort() gets the port
int	getSearchLimit() gets search limit
int	getSearchTimeout() returns search timeout
java.lang.String	getURL() gets the URL
java.util.Hashtable	list(java.lang.String baseDN) Lists the objects bound to the argument.
void	reconnect() reconnects to the server.
void	removePropertyChangeListener(java.beans.PropertyChangeListener l)
void	renameEntry(java.lang.String oldDN, java.lang.String newDN) renames an object in an LDAP database.
void	renameEntry(java.lang.String oldDN, java.lang.String newDN, boolean deleteOldDN) renames an object in an LDAP database.
java.util.Hashtable	search(java.lang.String filter, int searchScope) issues a specified search to the MDS.
java.util.Hashtable	search(java.lang.String filter, java.lang.String[] attrToReturn, int searchScope) issues a specified search to the MDS starting from the base DN.
java.util.Hashtable	search(java.lang.String baseDN, java.lang.String filter, int searchScope) issues a specified search to the MDS starting from the base DN.
java.util.Hashtable	search(java.lang.String baseDN, java.lang.String filter, java.lang.String[] attrToReturn, int searchScope) issues a specified search to the MDS starting from the base DN.
javax.naming.NamingEnumeration	searchl(java.lang.String baseDN, java.lang.String filter, java.lang.String[] attrToReturn, int searchScope) Issues a search starting from the basDN.
void	setBaseDN(java.lang.String baseDN) sets the baseDN to the specified value
void	setHostname(java.lang.String hostname) sets the hostname to the specified value
void	setLdapVersion(int newVersion) sets ldap protocol version
void	setPort(java.lang.String port) Sets the port to the specified value
void	setSearchLimit(int newLimit) sets search limit - number of returned entries
void	setSearchTimeout(int newTimeout) sets search timeout
void	updateAttribute(java.lang.String dn, MDSResult at) updates attributes of an entry.
void	updateEntry(java.lang.String dn, MDSResult at) updates specifed dn with attributes

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

limit

protected int limit

timeout

protected int timeout

version

protected int version

SUBTREE_SCOPE

public static final int SUBTREE_SCOPE

ONELEVEL_SCOPE

public static final int ONELEVEL_SCOPE

OBJECT_SCOPE

public static final int OBJECT_SCOPE

DEFAULT_CTX

protected static final java.lang.String DEFAULT_CTX

ctx

protected javax.naming.ldap.LdapContext ctx

env

protected java.util.Properties env

Constructor Detail

MDS

public MDS()

initilaizes a connetion to the MDS database with its default values

MDS

public MDS(java.lang.String hostname,
           java.lang.String port)

initilaizes a connetion to the MDS database to the speified host and port

Parameters:

hostname - specifies the hostname to which to connect

port - is the port on which the conection is established

MDS

public MDS(java.lang.String hostname,
           java.lang.String port,
           java.lang.String baseDN)

initilaizes a connetion to the MDS database to the speified host and port

Parameters:

hostname - specifies the hostname to which to connect

port - is the port on which the conection is established

baseDN - is the base DN from which searches are rooted

MDS

public MDS(GlobusURL spec)

initilaizes a connetion to the MDS database using the specified LDAP URL

Parameters:

spec - the LDAP URL spec from which connection information is derived

Method Detail

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener l)

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener l)

setBaseDN

public void setBaseDN(java.lang.String baseDN)

sets the baseDN to the specified value

Parameters:

baseDN -

getBaseDN

public java.lang.String getBaseDN()

returns the baseDN currently used

Returns:

DN the baseDN

setPort

public void setPort(java.lang.String port)

Sets the port to the specified value

Parameters:

port -

getPort

public java.lang.String getPort()

gets the port

Returns:

port the port

setHostname

public void setHostname(java.lang.String hostname)

sets the hostname to the specified value

Parameters:

hostname -

getHostname

public java.lang.String getHostname()

gets the hostname

Returns:

hostname gets the hostname

getURL

public java.lang.String getURL()

gets the URL

Returns:

the url string

setSearchTimeout

public void setSearchTimeout(int newTimeout)

sets search timeout

Parameters:

newTimeout -

getSearchTimeout

public int getSearchTimeout()

returns search timeout

Returns:

int timeout

setSearchLimit

public void setSearchLimit(int newLimit)

sets search limit - number of returned entries

Parameters:

newLimit -

getSearchLimit

public int getSearchLimit()

gets search limit

Returns:

int search limit

setLdapVersion

public void setLdapVersion(int newVersion)

sets ldap protocol version

Parameters:

newVersion -

getLdapVersion

public int getLdapVersion()

gets ldap protocol version

Returns:

ldap version 2 or 3

connect

public void connect()
             throws MDSException

connects to the specified server

Throws:

an - MDSexception if unable to connect

MDSException -

connect

public void connect(java.lang.String managerDN,
                    java.lang.String password)
             throws MDSException

connects and authenticates to the specified server

Parameters:

managerDN - specifies the distingushed name of the directory manager or user

password - specifies the password of the directory manager or user

Throws:

an - MDSexception if unable to connect

MDSException -

disconnect

public void disconnect()
                throws MDSException

disconnects from the MDS server

Throws:

an - MDSexception if failed to disconnect

reconnect

public void reconnect()
               throws MDSException

reconnects to the server.

Throws:

an - MDSexception if unable to reconnect

search

public java.util.Hashtable search(java.lang.String filter,
                                  int searchScope)
                           throws MDSException

issues a specified search to the MDS. The search returns all attributes.

Parameters:

filter - a common LDAP filter

searchScope - sets the scope of the search

Returns:

the result is returned in a hashtable of MDSResult

Throws:

an - MDSexception if something goes bad

search

public java.util.Hashtable search(java.lang.String filter,
                                  java.lang.String[] attrToReturn,
                                  int searchScope)
                           throws MDSException

issues a specified search to the MDS starting from the base DN.

Parameters:

filter - a common LDAP filter

attrToReturn -

searchScope - sets the scope of the search

Returns:

the result is returned in a hashtable of MDSResult

Throws:

an - MDSexception if something goes bad

search

public java.util.Hashtable search(java.lang.String baseDN,
                                  java.lang.String filter,
                                  int searchScope)
                           throws MDSException

issues a specified search to the MDS starting from the base DN. The search returns all attributes.

Parameters:

baseDN -

filter - a common LDAP filter

searchScope - sets the scope of the search

Returns:

the result is returned in a hashtable of MDSResult

Throws:

an - MDSexception if something goes bad

search

public java.util.Hashtable search(java.lang.String baseDN,
                                  java.lang.String filter,
                                  java.lang.String[] attrToReturn,
                                  int searchScope)
                           throws MDSException

issues a specified search to the MDS starting from the base DN.

Parameters:

baseDN - the base DN from which the

filter - a common LDAP filter

attrToReturn - an array of attributes to be returned

searchScope - sets the scope of the search

Returns:

the result is returned in a hashtable of MDSResult

Throws:

an - MDSexception if something goes bad

MDSException -

searchl

public javax.naming.NamingEnumeration searchl(java.lang.String baseDN,
                                              java.lang.String filter,
                                              java.lang.String[] attrToReturn,
                                              int searchScope)
                                       throws javax.naming.NamingException

Issues a search starting from the basDN.

Parameters:

baseDN - the base dn from which the search is started

filter - the filter for the search

attrToReturn - an array of attributes to return

searchScope - The search scope

Returns:

returns the result as NamingEnumeration

Throws:

javax.naming.NamingException - when an LDAP error occurs.

list

public java.util.Hashtable list(java.lang.String baseDN)
                         throws MDSException

Lists the objects bound to the argument.

Parameters:

baseDN -

Returns:

the result is returned in a hashtable of MDSResult

Throws:

an - MDSexception if something goes bad

getAttributes

public MDSResult getAttributes(java.lang.String dn)
                        throws MDSException

This methods returns that attributes of the specified distinguished name.

Parameters:

dn -

Returns:

Attributes the set of values that constitute the distinguished name

Throws:

an - MDSexception if something goes bad

getAttributes

public MDSResult getAttributes(java.lang.String dn,
                               java.lang.String[] attributes)
                        throws MDSException

This methods returns that attributes of the specified distinguished name.

Parameters:

dn -

attributes -

Returns:

Attributes the set a values that constitute the distinguished name

Throws:

an - MDSexception if something goes bad

createConstraints

protected javax.naming.directory.SearchControls createConstraints(int scope,
                                                                  java.lang.String[] attrToReturn)

deleteEntry

public void deleteEntry(java.lang.String dn)
                 throws MDSException

deletes a specific object specified by the dn.

Parameters:

dn - the distinguished name of the object to be deleted.

Throws:

an - MDSexception if something goes bad

renameEntry

public void renameEntry(java.lang.String oldDN,
                        java.lang.String newDN)
                 throws MDSException

renames an object in an LDAP database.

Parameters:

oldDN -

newDN -

Throws:

an - MDSexception if something goes bad

renameEntry

public void renameEntry(java.lang.String oldDN,
                        java.lang.String newDN,
                        boolean deleteOldDN)
                 throws MDSException

renames an object in an LDAP database. the attribute occurs multiple times only the first one will be deleted.

Parameters:

oldDN -

newDN -

deleteOldDN - deletes old dn from the entry

updateEntry

public void updateEntry(java.lang.String dn,
                        MDSResult at)
                 throws MDSException

updates specifed dn with attributes

Parameters:

dn - the distinguished name of the object.

at -

Throws:

an - MDSexception if something goes bad

addEntry

public void addEntry(java.lang.String dn,
                     MDSResult at)
              throws MDSException

adds attributes specified in a Attributes to an Object.

Parameters:

dn - the distinguished name of the object.

at -

Throws:

an - MDSexception if something goes bad

deleteAttribute

public void deleteAttribute(java.lang.String dn,
                            java.lang.String attr)
                     throws MDSException

deletes a specific attribute of an entry. It removes the whole attribute with all its values.

Parameters:

dn - the distinguished name of the entry

attr - the attribute name of the attribute to be deleted.

Throws:

an - MDSexception if something goes bad

deleteValues

public void deleteValues(java.lang.String dn,
                         MDSResult at)
                  throws MDSException

deletes attributes of an entry.

Parameters:

dn - the distinguished name of the entry.

at - a set of attributes to delete

Throws:

an - MDSexception if something goes bad

updateAttribute

public void updateAttribute(java.lang.String dn,
                            MDSResult at)
                     throws MDSException

updates attributes of an entry.

Parameters:

dn - the distinguished name of the entry.

at - a set of attributes to replace or add

Throws:

an - MDSexception if something goes bad

addAttribute

public void addAttribute(java.lang.String dn,
                         MDSResult at)
                  throws MDSException

adds attributes to an entry.

Parameters:

dn - the distinguished name of the object.

at -

Throws:

an - MDSexception if something goes bad

deleteTree

public void deleteTree(java.lang.String dn,
                       boolean deleteItSelf)
                throws MDSException

deletes a subtree starting from dn

Parameters:

dn - the distinguished name of the object.

deleteItSelf - if set to true, it also deletes the dn

Throws:

an - MDSexception if something goes bad