com.apelon.dts.client.subset
Class SubsetQuery

java.lang.Object
  extended by com.apelon.apelonserver.client.BasicQuery
      extended by 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:

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.


    Copyright © 2011. All Rights Reserved.