com.ca.directory.jxplorer.broker
Class Broker

java.lang.Object
  |
  +--com.ca.directory.jxplorer.broker.Broker

All Implemented Interfaces:

DataSource, java.lang.Runnable

Direct Known Subclasses:

JNDIBroker, OfflineBroker, SchemaBroker

public abstract class Broker

extends java.lang.Object

implements java.lang.Runnable, DataSource

Field Summary

protected DataQuery	current
int	id
protected java.util.Vector	listeners
protected java.util.Vector	requestQueue

Constructor Summary

Broker()

Method Summary

void	addDataListener(DataListener l) Adds a data listener to every DataQuery generated by this broker.
void	clearException() Utility method for extended queries - allows a 'masked' exception to be cleared.
DataQuery	copyTree(DN oldNodeDN, DN newNodeDN) Copies the entry, and any child entries, identified by DN oldNodeDn to newNodeDN.
protected DataQuery	doCopyQuery(DataQuery request) Method for the Broker interface - chains to copyTree().
protected DataQuery	doEntryQuery(DataQuery request) Method for the Broker interface - chains to dirOp.read().
protected DataQuery	doExistsQuery(DataQuery request) Method for the Broker interface - chains to dirOp.exists().
protected DataQuery	doExtendedQuery(DataQuery request)
protected DataQuery	doGetAllOCsQuery(DataQuery request) Method for the Broker interface - chains to getObjectClasses().
protected DataQuery	doGetRecOCsQuery(DataQuery request) Method for the Broker interface - chains to getunthreadedGetRecOCs.
protected DataQuery	doListQuery(DataQuery request) Method for the Broker interface - chains to list().
protected DataQuery	doModifyQuery(DataQuery request) Method for the Broker interface - chains to modifyEntry().
protected DataQuery	doSearchQuery(DataQuery request) Method for the Broker interface - chains to search().
DataQuery	exists(DN nodeDN) Checks the existence of a particular entry by DN, without (necessarily) reading any attributes.
DataQuery	extendedRequest(DataQuery query) General Bail out - this allows the passing of a generic DataQuery object.
protected DataQuery	finish(DataQuery request) Sets the finish flag of a request and returns the query.
Broker	getBroker() As a way to directly access the directory broker, a DataSource MAY choose to publish the directory broker.
DataQuery	getChildren(DN nodeDN) gets the children of a particular DN as an enumeration
DataQuery	getCurrent() Returns the DataQuery currently being processed (if any).
abstract javax.naming.directory.DirContext	getDirContext() As a way to directly access the raw jndi directory context, a DataSource MAY choose to publish the directory connection.
DataQuery	getEntry(DN nodeDN) gets the attribute types and values for a particular DN
java.lang.Exception	getException() Utility method for extended queries - returns whether a 'masked' exception has occured.
DataQuery	getObjectClasses() Gets a list of all known schema object classes.
DataQuery	getRecommendedObjectClasses(DN dn) Gets a list of the object classes most likely to be used for the next Level of the DN...
java.util.Vector	getRequestQueue() Returns the vector of outstanding queries.
abstract javax.naming.directory.DirContext	getSchema() Returns a schema context (for getting object classes etc.)
boolean	hasRequests() Returns whether there are more DataQuerys pending.
abstract boolean	isActive() whether the data source is currently on-line.
abstract boolean	isModifiable() Checks whether the current data source is modifiable.
DataQuery	modifyEntry(DXEntry oldEntry, DXEntry newEntry) This changes an old entry to a new entry.
DataQuery	pop() Gets the next DataQuery from the request Queue, removing it from the queue as it does so.
protected boolean	processQueue() process all queue requests
protected void	processRequest(DataQuery request) Process a specific request.
DataQuery	push(DataQuery request) Adds a DataQuery to the request Queue.
void	registerStopMonitor(StopMonitor monitor) Registers a stop monitor that is used by the gui to allow user cancellation of in-progress broker actions.
void	removeDataListener(DataListener l) Removes a data listener from every DataQuery generated by this broker.
void	removeQuery(DataQuery query) Removes a particular query from the pending query list...
void	run() Wait until notified that something (presumably an addition to the queue) has occured.
DataQuery	search(DN nodeDN, java.lang.String filter, int searchLevel, java.lang.String[] returnAttributes) Executes a search request.
abstract boolean	unthreadedCopy(DN oldNodeDN, DN newNodeDN) Copies a DN representing a subtree to a new subtree, including copying all subordinate entries.
abstract boolean	unthreadedExists(DN checkMe) Checks the existance of a given entry.
abstract java.util.Vector	unthreadedGetAllOCs() Returns a complete list of all known object classes.
abstract java.util.Vector	unthreadedGetRecOCs(DN dn) Gets a list of the object classes most likely to be used for the next Level of the DN...
abstract DXNamingEnumeration	unthreadedList(DN searchbase) returns the next level of a directory tree, returning a Enumeration of the results
abstract boolean	unthreadedModify(DXEntry oldEntry, DXEntry newEntry) Update an entry with the designated DN.
abstract DXEntry	unthreadedReadEntry(DN entryDN, java.lang.String[] returnAttributes) Reads an entry with all its attributes from the directory.
abstract DXNamingEnumeration	unthreadedSearch(DN dn, java.lang.String filter, int search_level, java.lang.String[] returnAttributes) Performs a directory search.

Methods inherited from class java.lang.Object

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

Field Detail

requestQueue

protected java.util.Vector requestQueue

listeners

protected java.util.Vector listeners

id

public int id

current

protected DataQuery current

Constructor Detail

Broker

public Broker()

Method Detail

registerStopMonitor

public void registerStopMonitor(StopMonitor monitor)

Registers a stop monitor that is used by the gui to allow user cancellation of in-progress broker actions.

push

public DataQuery push(DataQuery request)

Adds a DataQuery to the request Queue. Primarily used by the DataSource methods to register requests.

pop

public DataQuery pop()

Gets the next DataQuery from the request Queue, removing it from the queue as it does so.

removeQuery

public void removeQuery(DataQuery query)

Removes a particular query from the pending query list...

hasRequests

public boolean hasRequests()

Returns whether there are more DataQuerys pending.

run

public void run()

Wait until notified that something (presumably an addition to the queue) has occured. When woken, process all queue requests, and then go back to waiting.

Specified by:

run in interface java.lang.Runnable

processQueue

protected boolean processQueue()

process all queue requests

processRequest

protected void processRequest(DataQuery request)

Process a specific request.

getChildren

public DataQuery getChildren(DN nodeDN)

Description copied from interface: DataSource

gets the children of a particular DN as an enumeration

Specified by:

getChildren in interface DataSource

Parameters:

nodeDN - the DN to retrieve children for

Returns:

a DataQuery that may be queried using .getEnumeration() to obtain an enumeration of NameClassPair-s to be the sub-nodes of the given node.

getEntry

public DataQuery getEntry(DN nodeDN)

Description copied from interface: DataSource

gets the attribute types and values for a particular DN

Specified by:

getEntry in interface DataSource

Parameters:

nodeDN - the DN to retrieve attribute data for

Returns:

a DataQuery that may be queried using .getEntry() to obtain a DXEntry object containing attribute objects corresponding to the name/value(s) of the DN.

exists

public DataQuery exists(DN nodeDN)

Description copied from interface: DataSource

Checks the existence of a particular entry by DN, without (necessarily) reading any attributes.

Specified by:

exists in interface DataSource

Returns:

a DataQuery that may be queried using .getStatus() to obtain a boolean true if the node exists, or false if it don't.

getObjectClasses

public DataQuery getObjectClasses()

Description copied from interface: DataSource

Gets a list of all known schema object classes.

Specified by:

getObjectClasses in interface DataSource

Returns:

all known object classes, as . This will be null if this data source does not support this feature.

getRecommendedObjectClasses

public DataQuery getRecommendedObjectClasses(DN dn)

Description copied from interface: DataSource

Gets a list of the object classes most likely to be used for the next Level of the DN...

Specified by:

getRecommendedObjectClasses in interface DataSource

Parameters:

dn - the dn of the parent to determine likely child object classes for

Returns:

list of recommended object classes...

modifyEntry

public DataQuery modifyEntry(DXEntry oldEntry,
                             DXEntry newEntry)

Description copied from interface: DataSource

This changes an old entry to a new entry. If the distinguished name has changed, the object is moved. If the oldEntry is null, the object is created, or overwritten. If the newEntry is null, the object is deleted, along with any subentries.

Specified by:

modifyEntry in interface DataSource

Parameters:

oldEntry - the original entry (may be null if adding a new entry).

newEntry - the new entry (may be null if deleting the entry).

copyTree

public DataQuery copyTree(DN oldNodeDN,
                          DN newNodeDN)

Description copied from interface: DataSource

Copies the entry, and any child entries, identified by DN oldNodeDn to newNodeDN.

Specified by:

copyTree in interface DataSource

Parameters:

oldNodeDN - the entry or subtree apexto copy from

newNodeDN - the entry/subtree apex to copy to

search

public DataQuery search(DN nodeDN,
                        java.lang.String filter,
                        int searchLevel,
                        java.lang.String[] returnAttributes)

Description copied from interface: DataSource

Executes a search request.

Specified by:

search in interface DataSource

Parameters:

nodeDN - the root DN to start searching from

filter - the ldap string filter for the search

returnAttributes - an array of attributes that the search should return. or the entire sub tree.

extendedRequest

public DataQuery extendedRequest(DataQuery query)

Description copied from interface: DataSource

General Bail out - this allows the passing of a generic DataQuery object. The DataSource will run that object's 'extendedRequest' method.

Specified by:

extendedRequest in interface DataSource

Returns:

returns the same query it was passed (for compatibility with similar methods)

addDataListener

public void addDataListener(DataListener l)

Adds a data listener to every DataQuery generated by this broker. For threading simplicity, no data listeners are added to DataQuerys allready in the request queue.

While it is not an error to register a listener multiple times, a listener will still only be notified once.

Specified by:

addDataListener in interface DataSource

Parameters:

l - the listener to be notified when the data operation has been completed.

removeDataListener

public void removeDataListener(DataListener l)

Removes a data listener from every DataQuery generated by this broker.

Specified by:

removeDataListener in interface DataSource

Parameters:

l - the listener to be notified when the data is ready.

isModifiable

public abstract boolean isModifiable()

Description copied from interface: DataSource

Checks whether the current data source is modifiable. (Nb., a directory may have different access controls defined on different parts of the directory: if this is the case, the directory may return true to isModifiable(), however a particular modify attempt may still fail.

Specified by:

isModifiable in interface DataSource

Returns:

whether the directory is modifiable

getDirContext

public abstract javax.naming.directory.DirContext getDirContext()

Description copied from interface: DataSource

As a way to directly access the raw jndi directory context, a DataSource MAY choose to publish the directory connection.

Specified by:

getDirContext in interface DataSource

Returns:

the jndi directory context - may be null.

isActive

public abstract boolean isActive()

Description copied from interface: DataSource

whether the data source is currently on-line.

Specified by:

isActive in interface DataSource

Returns:

on-line status

getSchema

public abstract javax.naming.directory.DirContext getSchema()

Description copied from interface: DataSource

Returns a schema context (for getting object classes etc.)

Specified by:

getSchema in interface DataSource

finish

protected DataQuery finish(DataQuery request)

Sets the finish flag of a request and returns the query. Often overloaded by derived broker classes.

getCurrent

public DataQuery getCurrent()

Returns the DataQuery currently being processed (if any).

Returns:

the current DataQuery (may be null if there is none).

getRequestQueue

public java.util.Vector getRequestQueue()

Returns the vector of outstanding queries.

Returns:

a vector of (DataQuery).

doExtendedQuery

protected DataQuery doExtendedQuery(DataQuery request)

doExistsQuery

protected DataQuery doExistsQuery(DataQuery request)

Method for the Broker interface - chains to dirOp.exists().

doListQuery

protected DataQuery doListQuery(DataQuery request)

Method for the Broker interface - chains to list().

doEntryQuery

protected DataQuery doEntryQuery(DataQuery request)

Method for the Broker interface - chains to dirOp.read().

doSearchQuery

protected DataQuery doSearchQuery(DataQuery request)

Method for the Broker interface - chains to search().

doModifyQuery

protected DataQuery doModifyQuery(DataQuery request)

Method for the Broker interface - chains to modifyEntry().

doCopyQuery

protected DataQuery doCopyQuery(DataQuery request)

Method for the Broker interface - chains to copyTree().

doGetRecOCsQuery

protected DataQuery doGetRecOCsQuery(DataQuery request)

Method for the Broker interface - chains to getunthreadedGetRecOCs.

doGetAllOCsQuery

protected DataQuery doGetAllOCsQuery(DataQuery request)

Method for the Broker interface - chains to getObjectClasses().

unthreadedList

public abstract DXNamingEnumeration unthreadedList(DN searchbase)

returns the next level of a directory tree, returning a Enumeration of the results

Returns:

list of results (NameClassPair); the next layer of the tree...

unthreadedSearch

public abstract DXNamingEnumeration unthreadedSearch(DN dn,
                                                     java.lang.String filter,
                                                     int search_level,
                                                     java.lang.String[] returnAttributes)

Performs a directory search.

Parameters:

filter - the non-null filter to use for the search

search_level - whether to search the base object, the next level or the whole subtree.

returnAttributes - a vector of string names of attributes to return in the search. (null means 'return all entries', a zero length array means 'return no attributes'.)

Returns:

list of results ('SearchResult's); the next layer of the tree...

unthreadedCopy

public abstract boolean unthreadedCopy(DN oldNodeDN,
                                       DN newNodeDN)

Copies a DN representing a subtree to a new subtree, including copying all subordinate entries.

Parameters:

oldNodeDN - the original DN of the sub tree root to be copied (may be a single entry).

newNodeDN - the target DN for the tree to be moved to.

Returns:

the operation's success status

unthreadedExists

public abstract boolean unthreadedExists(DN checkMe)

Checks the existance of a given entry.

Returns:

whether the entry could be found in the directory.

unthreadedGetAllOCs

public abstract java.util.Vector unthreadedGetAllOCs()

Returns a complete list of all known object classes.

unthreadedReadEntry

public abstract DXEntry unthreadedReadEntry(DN entryDN,
                                            java.lang.String[] returnAttributes)

Reads an entry with all its attributes from the directory.

Parameters:

returnAttributes - a vector of string names of attributes to return in the search. (null means 'return all entries', a zero length array means 'return no attributes'.)

unthreadedModify

public abstract boolean unthreadedModify(DXEntry oldEntry,
                                         DXEntry newEntry)

Update an entry with the designated DN.

Returns:

the operation's success status

unthreadedGetRecOCs

public abstract java.util.Vector unthreadedGetRecOCs(DN dn)

Gets a list of the object classes most likely to be used for the next Level of the DN...

Parameters:

dn - the dn of the parent to determine likely child object classes for

Returns:

list of recommended object classes...

getException

public java.lang.Exception getException()

Utility method for extended queries - returns whether a 'masked' exception has occured.

Returns:

the exception, or null if there is none.

clearException

public void clearException()

Utility method for extended queries - allows a 'masked' exception to be cleared.

getBroker

public Broker getBroker()

As a way to directly access the directory broker, a DataSource MAY choose to publish the directory broker.

Specified by:

getBroker in interface DataSource

Returns:

the Broker - may be null.