com.apelon.dts.client.subset
Class SubsetQuery

java.lang.Object
  com.apelon.apelonserver.client.BasicQuery
      com.apelon.dts.client.subset.SubsetQuery

public abstract class SubsetQuery
extends BasicQuery

Provides subset related query and edit methods.

Requests related to navigation of a subset hierarchy are provided in NavQuery. Requests for searching against concepts in a subset are provided in SearchQuery.

A SubsetEvent is generated for the following actions:

• A new subset is added.
• A subset is updated.
• A subset is built.
• A subset is deleted.

If you have two instances of SubsetQuery and you would like to share the listeners between them, then you can code something like this.

 SubsetQuery sq1 = null;
 SubsetQuery sq2 = null;

 // Initialization code for sq1 and sq2

 sq2.addSubsetListener(sq1.getSubsetListener());
 // Now any event from sq2 will be available to sq1 listeners
 

Copyright: Copyright (c) 2005

Company: Apelon, Inc.

Since:

3.4.0

Version:

DTS 3.4.0

Author:

Apelon, Inc.

Field Summary

Fields inherited from class com.apelon.apelonserver.client.BasicQuery

ADMIN, queryHeader

Constructor Summary

protected	SubsetQuery()
protected	SubsetQuery(boolean isValidating)

Method Summary

Subset	add(Subset subset) Adds a Subset to the knowledgebase.
void	addSubsetListener(SubsetListener sl) Adds the given SubsetListener if it is not already added.
boolean	build(int subsetId) Computes the concepts for a subset.
static SubsetQuery	createInstance(ServerConnection sc)
static SubsetQuery	createInstance(ServerConnection sc, boolean isValidating)
boolean	delete(int subsetId) Deletes a Subset based on its id.
boolean	export(int subsetId, int namespaceId, long requestId) Exports a Subset to the given namespace.
void	exportSubsetExpression(int subsetId, Writer out) Exports a subset expression to a given output stream.
Subset	fetch(int subsetId) Returns a subset matching the given subset id.
Subset	fetch(String subsetName) Returns a subset matching the given subset name.
int	fetchConceptCount(Subset subset) Returns the number of concepts in a given Subset.
DTSConcept[]	fetchConcepts(int subsetId) Returns a list of DTSConcept for a given Subset.
DTSConcept[]	fetchConcepts(int subsetId, ConceptAttributeSetDescriptor casd) Returns a list of DTSConcept for a given Subset.
Subset[]	fetchConceptSubsets(int conceptId, int conceptNamespaceId) Retrieves the list of subsets which contain the given concept.
int[]	fetchNamespaces(int subsetId) Returns a single element array containing the namespace id linked to the subset.
DTSConcept[]	fetchPreview(PreviewOptions options) Fetches concepts from the subset when PreviewOptions.FULL is specified.
Subset[]	find(DataTypeFilter filter, SubsetDescriptor descriptor) Retrieves subsets based on the DataTypeFilter.
Subset[]	findAll(SubsetDescriptor descriptor) Retrieves all subsets.
protected void	fireSubsetEvent(SubsetEvent se)
SubsetListener	getSubsetListener() Get the SubsetListener.
void	importSubsetExpression(int subsetId, Reader in) Imports a subset expression from a given input stream to the subset provided by the user.
void	removeSubsetListener(SubsetListener sl) Removes the given SubsetListener if it was added earlier.
boolean	update(SubsetUpdate subsetUpdate) Updates subset with the details provided in the given SubsetUpdate.

Methods inherited from class com.apelon.apelonserver.client.BasicQuery

executeQuery, executeQueryNoParse, getServerConnection, initializeDtds, initializeDtds, ping, setVersion

Methods inherited from class java.lang.Object

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

Constructor Detail

SubsetQuery

protected SubsetQuery()

SubsetQuery

protected SubsetQuery(boolean isValidating)

Method Detail

createInstance

public static SubsetQuery createInstance(ServerConnection sc)
                                  throws IllegalArgumentException

Throws:

IllegalArgumentException

createInstance

public static SubsetQuery createInstance(ServerConnection sc,
                                         boolean isValidating)
                                  throws IllegalArgumentException

Throws:

IllegalArgumentException

getSubsetListener

public SubsetListener getSubsetListener()

Get the SubsetListener. This can be used to link the chain of subset listeners of this class to subset listener of another instance of SubsetQuery.

Returns:

SubsetListener

addSubsetListener

public void addSubsetListener(SubsetListener sl)

Adds the given SubsetListener if it is not already added.

Parameters:

sl - SubsetListener

removeSubsetListener

public void removeSubsetListener(SubsetListener sl)

Removes the given SubsetListener if it was added earlier.

Parameters:

sl - SubsetListener

fireSubsetEvent

protected void fireSubsetEvent(SubsetEvent se)

findAll

public Subset[] findAll(SubsetDescriptor descriptor)
                 throws DTSException

Retrieves all subsets. Subset object for each subset is populated with the information requested in SubsetDescriptor.

Parameters:

descriptor - SubsetDescriptor options for the subsets.

Returns:

an array of Subset. Returns an empty array if there are no Subsets.

Throws:

DTSException - if any error occurs in the method

find

public Subset[] find(DataTypeFilter filter,
                     SubsetDescriptor descriptor)
              throws DTSException

Retrieves subsets based on the DataTypeFilter. Subset object for each subset is populated with the information requested in SubsetDescriptor.

If no DataTypeFilter is provided (filter is null), all subsets are returned.

Parameters:

filter - The DataTypeFilter applied when retrieveing subsets.

descriptor - SubsetDescriptor options for the subsets.

Returns:

an array of Subset. Returns an empty array if there are no Subsets.

Throws:

DTSException - if any error occurs in the method

fetch

public Subset fetch(int subsetId)
             throws DTSException

Returns a subset matching the given subset id. All fields of Subset object are populated.

Parameters:

subsetId - The subset id

Returns:

Subset or null if subset does not exist

Throws:

DTSException - if any error occurs in the method

fetch

public Subset fetch(String subsetName)
             throws DTSException

Returns a subset matching the given subset name. All fields of Subset object are populated.

Parameters:

subsetName - The subset name

Returns:

Subset or null if subset does not exist

Throws:

DTSException - if any error occurs in the method

fetchConceptSubsets

public Subset[] fetchConceptSubsets(int conceptId,
                                    int conceptNamespaceId)
                             throws DTSException

Retrieves the list of subsets which contain the given concept.

The Subset objects have only id and name fields populated.

Parameters:

conceptId - the concept

conceptNamespaceId - the namespace id of the concept above

Returns:

an array of Subset. Returns an empty array if there are no Subsets.

Throws:

DTSException - if any error occurs in the method

add

public Subset add(Subset subset)
           throws DTSException

Adds a Subset to the knowledgebase.

This does not compute the expression or build the subset hierarchy.

A SubsetEvent is generated if the subset is added successfully. The action for this event is set to SubsetEvent.ACTION_ADD

Parameters:

subset - The Subset to be stored.

Returns:

The stored Subset or null if subset is not added.

Note: Id of the Subset is generated and set by the server.

Throws:

DTSException - if any error occurs in the method

fetchPreview

public DTSConcept[] fetchPreview(PreviewOptions options)
                          throws DTSException

Fetches concepts from the subset when PreviewOptions.FULL is specified. In the case PreviewOptions.DIFF_ADDITIONS or PreviewOptions.DIFF_DELETIONS, the difference between the result of the subset expression and the result of the subset stored in the knowledgebase (specified by the subset id in the PreviewOptions) is computed.

Note: The additions and deletions are limited by the setting the limit variable in the PreviewOptions object.

For example, first 500 subset preview results can be obtained as :

     Object[] concepts = new Object[0];
     PreviewOptions options = PreviewOptions.PREVIEW_FULL;
     options.setLimit( 500 );
     options.setSubsetExpression( subsetExpression );
     concepts = subsetQuery.fetchPreview( options );
 

And 1000 preview differences (additions and deletions) can be computed as :

      DTSConcept[][] diffs = new DTSConcept[2][];
      PreviewOptions addOptions = PreviewOptions.PREVIEW_DIFF_ADDITIONS;
      addOptions.setLimit( 1000 );
      addOptions.setSubsetExpression( modifiedSubsetExpression );
      addOptions.setSubsetId( storedSubsetId );
      diffs[0] = subsetQuery.fetchPreview( addOptions );

      PreviewOptions delOptions = PreviewOptions.PREVIEW_DIFF_DELETIONS;
      delOptions.setLimit( 1000 );
      delOptions.setSubsetExpression( modifiedSubsetExpression );
      delOptions.setSubsetId( storedSubsetId );
      diffs[1] = subsetQuery.fetchPreview( delOptions );
 

Parameters:

options - The PreviewOptions for computing previews.

Returns:

An array of DTSConcept based on above PreviewOptions

Throws:

DTSException - If there is a problem computing preview for the subset expression or if one of the following occurs:

• Subset expression parameter is null.
• PreviewOptions parameter is null.
• Syntax of Subset expression is not valid.
• Subset id is not set for preview difference feature.

See Also:

SubsetExpressionBuilder, PreviewOptions

build

public boolean build(int subsetId)
              throws DTSException

Computes the concepts for a subset. If the subset namespace is of type Ontylog or Ontylog Extension then the subset hierarchy is also built. Subset Hierarchy is the sub graph of the inferred concepts built using subset concepts.

A SubsetEvent is generated if the subset is built successfully. The action for this event is set to SubsetEvent.ACTION_MODIFY

Parameters:

subsetId - ID of the subset

Returns:

true if the concepts were computed and hierarchy was successfully built.

Throws:

DTSException - if any error occurs in the method

update

public boolean update(SubsetUpdate subsetUpdate)
               throws DTSException

Updates subset with the details provided in the given SubsetUpdate. Updates are only performed for non-null fields in SubsetUpdate.

A SubsetEvent is generated if the subset is updated successfully. The action for this event is set to SubsetEvent.ACTION_MODIFY

Parameters:

subsetUpdate - Update details as SubsetUpdate

Returns:

true if subset is updated, else false

Throws:

DTSException - if SubsetUpdate is null or server error occurs

delete

public boolean delete(int subsetId)
               throws DTSException

Deletes a Subset based on its id.

A SubsetEvent is generated if the subset is deleted successfully. The action for this event is set to SubsetEvent.ACTION_DELETE

Parameters:

subsetId - The id of the Subset

Returns:

true if the Subset was successfully deleted

Throws:

DTSException - if any error occurs in the method

fetchConcepts

public DTSConcept[] fetchConcepts(int subsetId,
                                  ConceptAttributeSetDescriptor casd)
                           throws DTSException

Returns a list of DTSConcept for a given Subset. Concept attributes are populated based on the given ConceptAttributeSetDescriptor.

Warning: For Subsets with large number of concepts, this may take a long time to complete.

Parameters:

subsetId - The id of the Subset

casd - ConceptAttributeSetDescriptor to use to populate concepts

Returns:

array of DTSConcept objects present in the given Subset. Returns an empty array if the given Subset doesn't exist.

Throws:

DTSException - if any error occurs in the method

fetchConcepts

public DTSConcept[] fetchConcepts(int subsetId)
                           throws DTSException

Returns a list of DTSConcept for a given Subset. Concepts are not populated with any attributes.

Warning: For Subsets with large number of concepts, this may take a long time to complete.

Parameters:

subsetId - The id of the Subset

Returns:

array of DTSConcept objects present in the given Subset. Returns an empty array if the given Subset doesn't exist.

Throws:

DTSException - if any error occurs in the method

fetchConceptCount

public int fetchConceptCount(Subset subset)
                      throws DTSException

Returns the number of concepts in a given Subset. Updates the concept count field of the Subset object.

Parameters:

subset - the Subset

Returns:

The number of concepts in the Subset. Returns 0 if the given Subset doesn't exist.

Throws:

DTSException - if Subset parameter is null or server error occurs

fetchNamespaces

public int[] fetchNamespaces(int subsetId)
                      throws DTSException

Returns a single element array containing the namespace id linked to the subset.

Parameters:

subsetId - The subset id

Returns:

a single element array containing the namespace id linked to the subset. Returns an empty array if the given Subset doesn't exist.

Throws:

DTSException - if server error occurs

export

public boolean export(int subsetId,
                      int namespaceId,
                      long requestId)
               throws DTSException

Exports a Subset to the given namespace.

Parameters:

subsetId - The id of the Subset.

namespaceId - The id of the namespace to which subset concepts are exported. The namespace must exist in the knowledgebase. It also must be editable and of type Thesaurus for the export to work. Any content in the namespace will be overwritten.

requestId - The request id to track and cancel this request

Returns:

true if the Subset was successfully exported to the namespace.

Throws:

DTSException - if

• Error occurs while exporting subset concepts to the namespace.
• The subset with the given subsetId does not exist.
• The namespace with the given namespaceId does not exist.
• Server error occurs.

importSubsetExpression

public void importSubsetExpression(int subsetId,
                                   Reader in)
                            throws DTSException,
                                   IOException

Imports a subset expression from a given input stream to the subset provided by the user.

Parameters:

subsetId - The id of the subset whose expression is to be updated.

in - The input reader which has a handle to the subset expression file.

Throws:

DTSException -

• Error occurs while importing subset concepts to the namespace.
• The subset with the given subsetId does not exist.
• Null arguments are provided.
• Any server error occurs.
  IOException - If any error is encountered handling the input stream.

exportSubsetExpression

public void exportSubsetExpression(int subsetId,
                                   Writer out)
                            throws DTSException,
                                   IOException

Exports a subset expression to a given output stream.

Parameters:

subsetId - The id of the subset whose expression is required to be exported.

out - The output reader to which the subset expression has to be written.

Throws:

DTSException -

• Error occurs while exporting subset concepts to the namespace.
• The subset with the given subsetId does not exist.
• Null arguments are provided.
• Any server error occurs.
  IOException - If any error is encountered handling the output stream.