com.ca.directory.jxplorer
Class DataQuery

java.lang.Object
  |
  +--com.ca.directory.jxplorer.DataQuery

Direct Known Subclasses:

JNDIBroker.DataConnectionQuery

public class DataQuery

extends java.lang.Object

Helper class for Broker, this encapsulates an ldap-like data request that is placed on the Broker queue for eventual resolution. Broker Request objects are intended to be used once, and then discarded.

Field Summary

protected boolean	cancelled
static int	COPY a modify request
static int	EXISTS an unknown type
static int	EXTENDED get recommended object classes request
protected java.util.Hashtable	extendedData
protected java.lang.String	filter
static int	GETALLOC a copy request
static int	GETRECOC get all object class request
int	id
static int	LIST a read of a single entry
protected java.util.Vector	listeners an extended data query: i.e. a user inherited extension class
static int	MODIFY a search query
protected DXEntry	myEntry
protected DXNamingEnumeration	myEnum
protected java.lang.Exception	myEx
protected boolean	myStatus
protected java.util.Vector	myVector
protected DXEntry	newEntry
protected DN	oldDN
protected DXEntry	oldEntry
static int	READENTRY an existance check query
protected boolean	ready
protected DN	requestDN
protected java.lang.String[]	returnAttrs
static int	SEARCH list the immediate children of an entry
protected int	searchLevel
protected boolean	squelched
protected int	type
static int	UNKNOWN The following gives the 'type' of the query.
protected boolean	working

Constructor Summary

DataQuery()

DataQuery(int type)
Constructor for Get all Object Class requests

DataQuery(int type, DN dn)
Constructor for List, Read Entry, Exists, and get Recommended Object Class requests.

DataQuery(int type, DN oldDN, DN newDN)
Constructor for Copy requests

DataQuery(int type, DN dn, java.lang.String filter, int level, java.lang.String[] returnAttrs)
Constructor for Search requests

DataQuery(int type, DXEntry oldEntry, DXEntry newEntry)
Constructor for Modify requests

Method Summary

void	addDataListener(DataListener l) Used by thread-friendly application to register a listener that will be called when the request has been completed (or an error thrown).
void	cancel() Attempt to cancel this request by setting a cancelled flag and an exception.
void	clearException() This clears the exception status of a DataResult, indicating that the exception has been handled.
void	doExtendedRequest(Broker b) Users intending to make Extended requests should write (potentially anonymous) derived classes of DataQuery, extending this method.
java.lang.String	filter()
void	finish() Called when the operation is complete.
protected void	fireDataEvent() Notifies all interested listeners.
java.util.Hashtable	getAllExtendedData() This provides a method of returning arbitrary information from an extended request.
DXEntry	getEntry() A DXEntry from a 'getEntry()' DataSource operation.
DXNamingEnumeration	getEnumeration() A list of Name-Class Pairs from a 'getChildren()' DataSource operation.
java.lang.Exception	getException() Indicates that an error has occured.
java.lang.Object	getExtendedData(java.lang.String name) Returns a named data object from the extended data queries object store.
java.util.Vector	getObjectClasses() A vector of strings representing ObjectClasses from either a DataSource getObjectClasses() or a getRecommendedObjectClasses() operation.
java.lang.Object	getResult() Get the result of the request as a generic object (which must be cast correctly to be used).
boolean	getStatus() Returns the status of an operation.
int	getType()
java.lang.String	getTypeString() Utility translation method
boolean	hasException() Returns whether an error has occured.
boolean	isCancelled() Returns whether this request has been cancelled.
boolean	isRunning() Returns whether the query is currently being operated on by a broker.
boolean	isSquelched() Flags whether a data listener has already consumed this data query ('event'), and the data has been 'used up'.
DXEntry	newEntry()
DN	oldDN()
DXEntry	oldEntry()
boolean	ready() Used by some thread-friendly applications that wish to poll the state of the DataResult.
DN	requestDN()
java.lang.String[]	returnAttributes()
int	searchLevel()
DataQuery	setEntry(DXEntry d)
DataQuery	setEnum(DXNamingEnumeration d)
DataQuery	setException(java.lang.Exception e)
void	setExtendedData(java.lang.String name, java.lang.Object o) This provides a method for setting arbitrary information for the use of an extended request.
void	setRunning() Registers that this query is currently being operated on by a broker.
DataQuery	setStatus(boolean b)
DataQuery	setVector(java.util.Vector v) Unsynchronized Methods to set data variables
void	squelch() Prevents any other data listeners from using the data query.
java.lang.String	toString() Return a string representation of the Broker Request (usually for debugging).

Methods inherited from class java.lang.Object

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

Field Detail

UNKNOWN

public static final int UNKNOWN

The following gives the 'type' of the query.

See Also:

Constant Field Values

EXISTS

public static final int EXISTS

an unknown type

See Also:

Constant Field Values

READENTRY

public static final int READENTRY

an existance check query

See Also:

Constant Field Values

LIST

public static final int LIST

a read of a single entry

See Also:

Constant Field Values

SEARCH

public static final int SEARCH

list the immediate children of an entry

See Also:

Constant Field Values

MODIFY

public static final int MODIFY

a search query

See Also:

Constant Field Values

COPY

public static final int COPY

a modify request

See Also:

Constant Field Values

GETALLOC

public static final int GETALLOC

a copy request

See Also:

Constant Field Values

GETRECOC

public static final int GETRECOC

get all object class request

See Also:

Constant Field Values

EXTENDED

public static final int EXTENDED

get recommended object classes request

See Also:

Constant Field Values

listeners

protected java.util.Vector listeners

an extended data query: i.e. a user inherited extension class

type

protected int type

id

public int id

myStatus

protected boolean myStatus

myVector

protected java.util.Vector myVector

myEntry

protected DXEntry myEntry

myEnum

protected DXNamingEnumeration myEnum

myEx

protected java.lang.Exception myEx

requestDN

protected DN requestDN

oldDN

protected DN oldDN

oldEntry

protected DXEntry oldEntry

newEntry

protected DXEntry newEntry

filter

protected java.lang.String filter

returnAttrs

protected java.lang.String[] returnAttrs

searchLevel

protected int searchLevel

extendedData

protected java.util.Hashtable extendedData

ready

protected boolean ready

cancelled

protected boolean cancelled

working

protected boolean working

squelched

protected boolean squelched

Constructor Detail

DataQuery

public DataQuery()

DataQuery

public DataQuery(int type)

Constructor for Get all Object Class requests

DataQuery

public DataQuery(int type,
                 DN dn)

Constructor for List, Read Entry, Exists, and get Recommended Object Class requests.

DataQuery

public DataQuery(int type,
                 DN oldDN,
                 DN newDN)

Constructor for Copy requests

DataQuery

public DataQuery(int type,
                 DXEntry oldEntry,
                 DXEntry newEntry)

Constructor for Modify requests

DataQuery

public DataQuery(int type,
                 DN dn,
                 java.lang.String filter,
                 int level,
                 java.lang.String[] returnAttrs)

Constructor for Search requests

Method Detail

squelch

public void squelch()

Prevents any other data listeners from using the data query. Indicates that the current data listener has handled the data, and that no other data listener should bother. This method nullifies any data (including exception information).

isSquelched

public boolean isSquelched()

Flags whether a data listener has already consumed this data query ('event'), and the data has been 'used up'.

cancel

public void cancel()

Attempt to cancel this request by setting a cancelled flag and an exception. There is no way to 'uncancel' a request. The cancel flag should be picked up by the broker.

isCancelled

public boolean isCancelled()

Returns whether this request has been cancelled.

setRunning

public void setRunning()

Registers that this query is currently being operated on by a broker. This is cancelled when the query is 'finished()'.

isRunning

public boolean isRunning()

Returns whether the query is currently being operated on by a broker.

finish

public void finish()

Called when the operation is complete. While it is not an error to call this method multiple times, subsequent calls will have no effect.

fireDataEvent

protected void fireDataEvent()

Notifies all interested listeners. Note that the most recently added listener is notified first, giving it first option on handling any errors generated.

getTypeString

public java.lang.String getTypeString()

Utility translation method

toString

public java.lang.String toString()

Return a string representation of the Broker Request (usually for debugging).

Overrides:

toString in class java.lang.Object

getResult

public java.lang.Object getResult()

Get the result of the request as a generic object (which must be cast correctly to be used). (Usually for debugging).

setVector

public DataQuery setVector(java.util.Vector v)

Unsynchronized Methods to set data variables

setStatus

public DataQuery setStatus(boolean b)

setEntry

public DataQuery setEntry(DXEntry d)

setEnum

public DataQuery setEnum(DXNamingEnumeration d)

setException

public DataQuery setException(java.lang.Exception e)

ready

public boolean ready()

Used by some thread-friendly applications that wish to poll the state of the DataResult. Returns false until the data request has been completed (which includes an error occurring).

Returns:

true if the request has been completed.

addDataListener

public void addDataListener(DataListener l)

Used by thread-friendly application to register a listener that will be called when the request has been completed (or an error thrown).

Note that this listener is somewhat unusual, as it will only ever trigger a maximum of one time.

if this method is called on a DataResult that has already been completed, it will be triggered immediately. This may cause listener code to be triggered before any code subsequent to the addDataListener() call.

Parameters:

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

getStatus

public boolean getStatus()
                  throws javax.naming.NamingException

Returns the status of an operation. This will block until the transaction has finished, so thread friendly applications should wait until the DataResult is 'ready' before calling this method.

This method should be used to read the response from DataSource methods modifyEntry() and copyTree(), and DataSource operations such as exists() and isActive(). Throws a NamingException if called inapropriately (i.e. if no result of this type would be possible).

Returns:

the success status of the operation.

javax.naming.NamingException

getEnumeration

public DXNamingEnumeration getEnumeration()
                                   throws javax.naming.NamingException

A list of Name-Class Pairs from a 'getChildren()' DataSource operation. This will block until the transaction has finished, so thread friendly applications should wait until the DataResult is 'ready' before calling this method.

Throws a NamingException if called inapropriately (i.e. if no result of this type would be possible). This method should be used to read the response from DataSource getChildren() method.

Returns:

the NameClass pairs representing the children of a given entry, or of SearchResults representing the result of a search request.

javax.naming.NamingException

getEntry

public DXEntry getEntry()
                 throws javax.naming.NamingException

A DXEntry from a 'getEntry()' DataSource operation. This will block until the transaction has finished, so thread friendly applications should wait until the DataResult is 'ready' before calling this method.

Throws a NamingException if called inapropriately (i.e. if no result of this type would be possible). This method should be used to read the response from DataSource getEntry() method.

javax.naming.NamingException

getObjectClasses

public java.util.Vector getObjectClasses()
                                  throws javax.naming.NamingException

A vector of strings representing ObjectClasses from either a DataSource getObjectClasses() or a getRecommendedObjectClasses() operation. This will block until the transaction has finished, so thread friendly applications should wait until the DataResult is 'ready' before calling this method.

Throws a NamingException if called inapropriately (i.e. if no result of this type would be possible). This method should be used to read the response from DataSource getObjectClasses() or a getRecommendedObjectClasses() method.

javax.naming.NamingException

getException

public java.lang.Exception getException()

Indicates that an error has occured. This will block until the transaction has finished, so thread friendly applications should wait until the DataResult is 'ready' before calling this method.

It returns null if there is no exception.

Returns:

the exception experienced by the directory operation, or null if no error found.

hasException

public boolean hasException()

Returns whether an error has occured. This will block until the transaction has finished, so thread friendly applications should wait until the DataResult is 'ready' before calling this method.

It returns false if there is no exception.

Returns:

whether an exception occured in the execution of this query

clearException

public void clearException()

This clears the exception status of a DataResult, indicating that the exception has been handled. It is not an error to call this method if no exception exists, and this method has no effect on exceptions that may occur later (e.g. if this method is called before the DataResult is ready() it may have no effect.)

getType

public int getType()

requestDN

public DN requestDN()

oldDN

public DN oldDN()

oldEntry

public DXEntry oldEntry()

newEntry

public DXEntry newEntry()

filter

public java.lang.String filter()

returnAttributes

public java.lang.String[] returnAttributes()

searchLevel

public int searchLevel()

getAllExtendedData

public java.util.Hashtable getAllExtendedData()

This provides a method of returning arbitrary information from an extended request.

Returns:

a hashtable of named objects (use addExtendedData to set these).

getExtendedData

public java.lang.Object getExtendedData(java.lang.String name)

Returns a named data object from the extended data queries object store.

setExtendedData

public void setExtendedData(java.lang.String name,
                            java.lang.Object o)

This provides a method for setting arbitrary information for the use of an extended request.

doExtendedRequest

public void doExtendedRequest(Broker b)

Users intending to make Extended requests should write (potentially anonymous) derived classes of DataQuery, extending this method. Derived class writers should be carefull to only use the *unthreaded* methods of the Broker, in order to avoid possible thread problems.