CEConstraint (NetCDF-Java All API v5.7.0)

java.lang.Object
- dap4.core.ce.CEConstraint

Direct Known Subclasses:

Universal
```
public class CEConstraint
extends java.lang.Object
```
A Constraint is a structure containing a parsed representation of a constraint expression. Its purpose is define a subset of interest of a dataset.
The constraint object is defined with respect to some underlying DMR. It defines a subset view over that DMR in that it specifies a set of declarations (variables, enums, dimensions, groups) to be included. For each such variable, the constraint specifies any overriding of the dimensions of the variables. Additionally, each variable (if appropriate) may have a filter expr.
Thus, there are three 'sub' constraints within a full constraint. 1. Referencing - is a variable from the underlying dataset included in the constraint, directly (by or indirectly: e.g. fields of a structure when only the structure is referenced 2. Projection - the actual values of a variable to be included in the constraint; this is specified by a triple [start:stride:stop] for each dimension of a variable. 3. Selection (aka filters) - A predicate over the scalar fields of a row of a Sequence; if it evaluates to true, then that row matches the constraint.
There are multiple ways to effect a constraint. 1. Generate and test mode: the constraint is asked if a given element matches the constraint. E.g. a. For referencing, one might ask the constraint if a given variable or field is in the constraint b. For a projection filter, one might ask the constraint if a given set of dimension indices match the projection. c. For a selection filter, one might ask the constraint if a given sequence row matches the filter predicate 2. Iteration mode: the constraint provides an iterator that returns the elements matching the constraint. E.g. a. For referencing, the iterator would return all the variables and fields referenced in the constraint. b. For a projection filter, the iterator would return the successive sets of indices of the projection, or it could return the actual matching value. c. For a selection filter, the iterator would return either the row indices or the actual rows of a sequence that matched the filter predicate
3. Read mode: Sometimes, it may be more efficient to let the DataVariable object handle the constraint more directly. E.g. a. For example, if the data variable was backed by a netcdf file, then passing in the complete projection might be more efficient than pulling values 1 by 1. b. Similarly, if the sequence object had an associated btree, then it would be more efficient to allow the sequence object to evaluate the filter using the btree. Note that this requires analysis of the filter expression to see if the btree is usable.
Ideally, we would allow all three modes, but for now, only generate-and-test is implemented, and only a subset of that. Generate-and-test is provided for referencing and selection. It is not provided for projection (for now) because it essentially requires the inverse of iteration and that is fairly tricky.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

protected static class CEConstraint.Expand

protected static class CEConstraint.Segment

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`CEConstraint.Expand`
`protected static class`	`CEConstraint.Segment`

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.util.Map<DapNode,java.util.List<DapAttribute>>`	`attributes`
`protected static boolean`	`DEBUG`
`protected java.util.List<DapDimension>`	`dimrefs`
`protected DapDataset`	`dmr`
`protected java.util.List<DapEnumeration>`	`enums`
`protected CEConstraint.Expand`	`expansion`
`protected boolean`	`finished`
`protected java.util.List<DapGroup>`	`groups`
`protected static boolean`	`PARSEDEBUG`
`protected java.util.Map<DapDimension,DapDimension>`	`redef`
`protected java.util.Map<DapDimension,Slice>`	`redefslice`
`protected java.util.List<DapDimension>`	`refdims`
`protected java.util.List<CEConstraint.Segment>`	`segments` "Map" of variables (at all levels) to be included Maps variables -> associated slices and is modified by computdimensions().
`protected static java.util.Map<DapDataset,CEConstraint>`	`universals`
`protected java.util.List<DapVariable>`	`variables` Also keep a raw list of variables

Constructor Summary

Constructors
Constructor and Description

CEConstraint()

CEConstraint(DapDataset dmr)

Constructors
Constructor and Description
`CEConstraint()`
`CEConstraint(DapDataset dmr)`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addAttribute(DapNode node, DapAttribute attr)`
`void`	`addRedef(DapDimension dim, Slice slice)`
`void`	`addVariable(DapVariable var, java.util.List<Slice> slices)`
`protected static int`	`compare(java.lang.Object lvalue, java.lang.Object rvalue)`
`static CEConstraint`	`compile(java.lang.String sce, DapDataset dmr)`
`protected void`	`computedimensions()` Compute dimension related information using slicing and redef info.
`protected void`	`computeenums()` Walk all the included variables and accumulate the referenced enums
`protected void`	`computegroups()` Walk all the included declarations and accumulate the set of referenced groups
`void`	`contract()` Locate each Structure\|Sequence and: 1.
`protected boolean`	`contractR(DapStructure dstruct, java.util.Set<DapStructure> contracted)` Recursive helper
`protected void`	`dumpvar(CEConstraint.Segment seg, java.lang.StringBuilder buf, boolean forconstraint)` Recursive helper for tostring/toConstraintString
`protected java.lang.Object`	`eval(DapVariable var, DapSequence seq, D4Array record, CEAST expr)` Evaluate a filter with respect to a Sequence record.
`void`	`expand()` Locate each unexpanded Structure\|Sequence and: 1.
`protected int`	`expansionCount(DapStructure struct)` Count the number of fields of a structure that already in this view.
`protected CEConstraint.Segment`	`findSegment(DapVariable var)`
`protected int`	`findVariableIndex(DapVariable var)`
`CEConstraint`	`finish()` Finish creating this Constraint.
`java.util.List<DapDimension>`	`getConstrainedDimensions(DapVariable var)`
`java.util.List<Slice>`	`getConstrainedSlices(DapVariable var)`
`DapDataset`	`getDMR()`
`DapDimension`	`getRedefDim(DapDimension orig)`
`static CEConstraint`	`getUniversal(DapDataset dmr)`
`boolean`	`isUniversal()`
`protected boolean`	`isWholeCompound(DapStructure dstruct)` See if a structure is "whole", which means that none of its fields is missing from the constraint, all of fields use default (non-constrained) dimension), and all of its fields are also whole.
`boolean`	`match(DapVariable sqvar, DapSequence seq, D4Array rec)` Selection X match
`protected boolean`	`matches(DapVariable var, DapSequence seq, D4Array rec, CEAST filter)` Evaluate a filter with respect to a Sequence record.
`boolean`	`references(DapNode node)` Reference X match
`static void`	`release(DapDataset dmr)`
`void`	`setFilter(DapVariable var, CEAST filter)`
`java.lang.String`	`toConstraintString()` Convert the view to a constraint string suitable for use in a URL, except not URL encoded.
`java.lang.String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - PARSEDEBUG
```
protected static final boolean PARSEDEBUG
```
    See Also:
    
    Constant Field Values
  - DEBUG
```
protected static final boolean DEBUG
```
    See Also:
    
    Constant Field Values
  - universals
```
protected static java.util.Map<DapDataset,CEConstraint> universals
```
  - dmr
```
protected DapDataset dmr
```
  - segments
```
protected java.util.List<CEConstraint.Segment> segments
```
    "Map" of variables (at all levels) to be included Maps variables -> associated slices and is modified by computdimensions(). Note that we keep the original insertion order
  - variables
```
protected java.util.List<DapVariable> variables
```
    Also keep a raw list of variables
  - redefslice
```
protected java.util.Map<DapDimension,Slice> redefslice
```
  - attributes
```
protected java.util.Map<DapNode,java.util.List<DapAttribute>> attributes
```
  - redef
```
protected java.util.Map<DapDimension,DapDimension> redef
```
  - dimrefs
```
protected java.util.List<DapDimension> dimrefs
```
  - enums
```
protected java.util.List<DapEnumeration> enums
```
  - groups
```
protected java.util.List<DapGroup> groups
```
  - refdims
```
protected java.util.List<DapDimension> refdims
```
  - finished
```
protected boolean finished
```
  - expansion
```
protected CEConstraint.Expand expansion
```
- Constructor Detail
  - CEConstraint
```
public CEConstraint()
```
  - CEConstraint
```
public CEConstraint(DapDataset dmr)
```
- Method Detail
  - getUniversal
```
public static CEConstraint getUniversal(DapDataset dmr)
```
  - release
```
public static void release(DapDataset dmr)
```
  - compare
```
protected static int compare(java.lang.Object lvalue,
                             java.lang.Object rvalue)
                      throws DapException
```
    Throws:
    
    DapException
  - eval
```
protected java.lang.Object eval(DapVariable var,
                                DapSequence seq,
                                D4Array record,
                                CEAST expr)
                         throws DapException
```
    Evaluate a filter with respect to a Sequence record. Assumes the filter has been canonicalized so that the lhs is a variable.
    
    Parameters:
    
    seq - the template
    
    record - the record to evaluate
    
    expr - the filter
    
    Returns:
    
    the value of the expression (usually a Boolean)
    
    Throws:
    
    DapException
  - isUniversal
```
public boolean isUniversal()
```
  - getDMR
```
public DapDataset getDMR()
```
  - getRedefDim
```
public DapDimension getRedefDim(DapDimension orig)
```
  - addRedef
```
public void addRedef(DapDimension dim,
                     Slice slice)
```
  - addVariable
```
public void addVariable(DapVariable var,
                        java.util.List<Slice> slices)
                 throws DapException
```
    Throws:
    
    DapException
  - addAttribute
```
public void addAttribute(DapNode node,
                         DapAttribute attr)
```
  - setFilter
```
public void setFilter(DapVariable var,
                      CEAST filter)
```
  - getConstrainedSlices
```
public java.util.List<Slice> getConstrainedSlices(DapVariable var)
                                           throws DapException
```
    Throws:
    
    DapException
  - getConstrainedDimensions
```
public java.util.List<DapDimension> getConstrainedDimensions(DapVariable var)
```
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - finish
```
public CEConstraint finish()
                    throws DapException
```
    Finish creating this Constraint.
    
    Returns:
    
    this - fluent interface
    
    Throws:
    
    DapException
  - toConstraintString
```
public java.lang.String toConstraintString()
```
    Convert the view to a constraint string suitable for use in a URL, except not URL encoded.
    
    Returns:
    
    constraint string
  - dumpvar
```
protected void dumpvar(CEConstraint.Segment seg,
                       java.lang.StringBuilder buf,
                       boolean forconstraint)
```
    Recursive helper for tostring/toConstraintString
    
    Parameters:
    
    seg -
    
    buf -
    
    forconstraint -
  - references
```
public boolean references(DapNode node)
```
    Reference X match
    
    Parameters:
    
    node - to test
    
    Returns:
    
    true if node is referenced by this constraint
  - match
```
public boolean match(DapVariable sqvar,
                     DapSequence seq,
                     D4Array rec)
              throws DapException
```
    Selection X match
    Evaluate a filter with respect to a Sequence record. Assumes the filter has been canonicalized.
    
    Parameters:
    
    seq - the template
    
    rec - the record to evaluate
    
    Returns:
    
    true if the filter matches the record
    
    Throws:
    
    DapException
  - matches
```
protected boolean matches(DapVariable var,
                          DapSequence seq,
                          D4Array rec,
                          CEAST filter)
                   throws DapException
```
    Evaluate a filter with respect to a Sequence record.
    
    Parameters:
    
    seq - the template
    
    rec - the record to evaluate
    
    filter - the filter
    
    Returns:
    
    true if a match
    
    Throws:
    
    DapException
  - findVariableIndex
```
protected int findVariableIndex(DapVariable var)
```
  - findSegment
```
protected CEConstraint.Segment findSegment(DapVariable var)
```
  - expand
```
public void expand()
```
    Locate each unexpanded Structure|Sequence and: 1. check that none of its fields is referenced => do not expand 2. add all of its fields as leaves Note that #2 may end up adding additional leaf structs &/or seqs
  - contract
```
public void contract()
```
    Locate each Structure|Sequence and: 1. check that all of its fields are referenced recursively and not constrained, otherwise ignore 2. contract by removing all of the fields of the Structure or Sequence. This is intended to be (not quite) the dual of expand();
  - contractR
```
protected boolean contractR(DapStructure dstruct,
                            java.util.Set<DapStructure> contracted)
```
    Recursive helper
    
    Parameters:
    
    dstruct - to contract
    
    contracted - set of already contracted compounds
    
    Returns:
    
    true if this structure was contracted, false otherwise
  - expansionCount
```
protected int expansionCount(DapStructure struct)
```
    Count the number of fields of a structure that already in this view.
    
    Parameters:
    
    struct - the dapstructure to check
    
    Returns:
    
    # of fields in this view
    
    Throws:
    
    DapException
  - isWholeCompound
```
protected boolean isWholeCompound(DapStructure dstruct)
```
    See if a structure is "whole", which means that none of its fields is missing from the constraint, all of fields use default (non-constrained) dimension), and all of its fields are also whole. This must be done recursively.
    
    Parameters:
    
    dstruct - to test
    
    Returns:
    
    true if this structure is whole.
  - computedimensions
```
protected void computedimensions()
                          throws DapException
```
    Compute dimension related information using slicing and redef info. In effect, this is where projection constraints are applied
    Assume that the constraint compiler has given us the following info:
    1. A list of the variables to include.
    2. A pair (DapDimension,Slice) for each redef
    3. For each variable in #1, a list of slices taken from the constraint expression
    Two products will be produced.
    1. The variables map will be modified so that the slices properly reflect any original or redef dimensions.
    2. A set, dimrefs, of all referenced original dimensions.
    The processing is as follows
    1. For each redef create a new redef dimension
    2. For each variable:
      
      if the variable is scalar, do nothing.
      if the variable has no associated slices, then make its new dimensions be the original dimensions.
      otherwise, walk the slices and create new dimensions from them; use redefs where indicated
    Throws:
    
    DapException
  - computeenums
```
protected void computeenums()
```
    Walk all the included variables and accumulate the referenced enums
  - computegroups
```
protected void computegroups()
```
    Walk all the included declarations and accumulate the set of referenced groups
  - compile
```
public static CEConstraint compile(java.lang.String sce,
                                   DapDataset dmr)
                            throws DapException
```
    Throws:
    
    DapException

Class CEConstraint

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PARSEDEBUG

DEBUG

universals

dmr

segments

variables

redefslice

attributes

redef

dimrefs

enums

groups

refdims

finished

expansion

Constructor Detail

CEConstraint

CEConstraint

Method Detail

getUniversal

release

compare

eval

isUniversal

getDMR

getRedefDim

addRedef

addVariable

addAttribute

setFilter

getConstrainedSlices

getConstrainedDimensions

toString

finish

toConstraintString

dumpvar

references

match

matches

findVariableIndex

findSegment

expand

contract

contractR

expansionCount

isWholeCompound

computedimensions

computeenums

computegroups

compile