uima-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marshall Schor <...@schor.com>
Subject Re: svn commit: r1762163 - /uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java
Date Mon, 26 Sep 2016 19:45:08 GMT
I see other changes now :-).

One is the generic typing.  I was thinking that the first call to create a
SelectFSs would "pass in the generic type" perhaps from an argument, or from a
receiving argument.  The rest of the API calls, once you had this object, would
propagate it.

It looks like you may have a nice extension - allowing the index and type
methods to change the generic type, from the receiving argument.

-Marshall

On 9/26/2016 3:37 PM, Marshall Schor wrote:
> Hi Richard,
>
> I see with this update that you converted javadoc style comments to // style.
>
> Was this to get these out of the javadocs? 
>
> For that purpose, it might look a bit better to use the
>
> /* (single *) ... */ style?
>
> Anyway, I'm in complete agreement that the Javadocs for these are missing and
> need to be written :-).  I had these other comments as an internal placeholder
> while the APIs got worked out, because once the javadocs go in, the file expands
> to the point where it's hard to see things IMHO :-).
>
> -Marshall
>
>
> On 9/25/2016 4:18 AM, rec@apache.org wrote:
>> Author: rec
>> Date: Sun Sep 25 08:18:09 2016
>> New Revision: 1762163
>>
>> URL: http://svn.apache.org/viewvc?rev=1762163&view=rev
>> Log:
>> [UIMA-5115] uv3 select() api for iterators and streams over CAS contents
>> - Chain generic types after selecting a type or index
>> - Comments are not JavaDoc - changing them into line comments instead of JavaDoc
comments
>>
>>
>> Modified:
>>     uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java
>>
>> Modified: uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java
>> URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java?rev=1762163&r1=1762162&r2=1762163&view=diff
>> ==============================================================================
>> --- uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java
(original)
>> +++ uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java
Sun Sep 25 08:18:09 2016
>> @@ -35,42 +35,37 @@ import org.apache.uima.jcas.tcas.Annotat
>>   */
>>  public interface SelectFSs<T extends FeatureStructure> {
>>    
>> -  /**
>> -   * If not specified, defaults to all FSs (unordered) unless AnnotationIndex implied
>> -   */
>> -  SelectFSs<T> index(String indexName);  
>> -  SelectFSs<T> index(FSIndex<T> index);
>> -
>> -  /**
>> -   * if not specified defaults to the index's uppermost type.  
>> -   */
>> -  SelectFSs<T> type(Type uimaType);
>> -  SelectFSs<T> type(String fullyQualifiedTypeName);
>> -  SelectFSs<T> type(int jcasClass_dot_type);
>> -  SelectFSs<T> type(Class<? extends TOP> jcasClass_dot_class);
>> +  // If not specified, defaults to all FSs (unordered) unless AnnotationIndex implied
>> +    // Methods take their generic type from the variable to which they are assigned
except for
>> +    // index(class) which takes it from its argument.
>> +  <N extends TOP> SelectFSs<N> index(String indexName);  
>> +  <N extends TOP> SelectFSs<N> index(FSIndex<N> index);
>> +
>> +  // If not specified defaults to the index's uppermost type.
>> +  // Methods take their generic type from the variable to which they are assigned
except for
>> +  // type(class) which takes it from its argument.
>> +  <N extends TOP> SelectFSs<N> type(Type uimaType);
>> +  <N extends TOP> SelectFSs<N> type(String fullyQualifiedTypeName);
>> +  <N extends TOP> SelectFSs<N> type(int jcasClass_dot_type);
>> +  <N extends TOP> SelectFSs<N> type(Class<N> jcasClass_dot_class);
>>      
>>  //  SelectFSs<T> shift(int amount); // incorporated into startAt 
>>    
>> -  /*********************************
>> -   * boolean operations
>> -   *********************************/
>> +  // ---------------------------------
>> +  // boolean operations
>> +  // ---------------------------------
>>  
>>    SelectFSs<T> matchType();      // exact type match (no subtypes)
>>    SelectFSs<T> matchType(boolean matchType); // exact type match (no subtypes)
>>    
>> -  /**
>> -   * only for AnnotationIndex
>> -   */
>> +  // only for AnnotationIndex
>>    SelectFSs<T> typePriority();
>>    SelectFSs<T> typePriority(boolean typePriority);
>>  
>>    SelectFSs<T> positionUsesType();           // ignored if not ordered index
>>    SelectFSs<T> positionUsesType(boolean positionUsesType); // ignored if not
ordered index
>>    
>> -  /**
>> -   * Filters while iterating over Annotations
>> -   **/
>> -  
>> +  // Filters while iterating over Annotations
>>    SelectFSs<T> nonOverlapping();  // AI known as unambiguous
>>    SelectFSs<T> nonOverlapping(boolean nonOverlapping); // AI
>>    
>> @@ -80,10 +75,7 @@ public interface SelectFSs<T extends Fea
>>    SelectFSs<T> skipEquals();                 
>>    SelectFSs<T> skipEquals(boolean skipEquals);
>>    
>> -  /**
>> -   * Miscellaneous
>> -   **/
>> -  
>> +  // Miscellaneous
>>    SelectFSs<T> allViews();
>>    SelectFSs<T> allViews(boolean allViews);
>>    
>> @@ -99,40 +91,40 @@ public interface SelectFSs<T extends Fea
>>  //  SelectFSs<T> noSubtypes();
>>  //  SelectFSs<T> noSubtypes(boolean noSubtypes);
>>  
>> -  /*********************************
>> -   * bounding limits specified
>> -   * as part of subselection style
>> -   *********************************/
>> -  
>> -  /*********************************
>> -   * starting position specification
>> -   * 
>> -   * Variations, controlled by: 
>> -   *   * typePriority
>> -   *   * positionUsesType
>> -   *   
>> -   * The positional specs imply starting at the 
>> -   *   - left-most (if multiple) FS at that position, or
>> -   *   - if no FS at the position, the next higher FS
>> -   *   - if !typePriority, equal test is only begin/end 
>> -   *     -- types ignored or not depending on positionUsesType 
>> -   *    
>> -   * shifts, if any, occur afterwards
>> -   *   - can be positive or negative
>> -   *********************************/
>> +  // ---------------------------------
>> +  // bounding limits specified
>> +  // as part of subselection style
>> +  // ---------------------------------
>> +  
>> +  // ---------------------------------
>> +  // starting position specification
>> +  // 
>> +  // Variations, controlled by: 
>> +  //   * typePriority
>> +  //   * positionUsesType
>> +  //   
>> +  // The positional specs imply starting at the 
>> +  //   - left-most (if multiple) FS at that position, or
>> +  //   - if no FS at the position, the next higher FS
>> +  //   - if !typePriority, equal test is only begin/end 
>> +  //     -- types ignored or not depending on positionUsesType 
>> +  //    
>> +  // shifts, if any, occur afterwards
>> +  //   - can be positive or negative
>> +  // ---------------------------------
>>    SelectFSs<T> startAt(TOP fs);  // Ordered
>>    SelectFSs<T> startAt(int begin, int end);   // AI
>>    
>>    SelectFSs<T> startAt(TOP fs, int shift);        // Ordered
>>    SelectFSs<T> startAt(int begin, int end, int shift);   // AI
>>      
>> -  /*********************************
>> -   * subselection based on bounds
>> -   *   - uses 
>> -   *     -- typePriority, 
>> -   *     -- positionUsesType, 
>> -   *     -- skipEquals
>> -   *********************************/
>> +  // ---------------------------------
>> +  // subselection based on bounds
>> +  //   - uses 
>> +  //     -- typePriority, 
>> +  //     -- positionUsesType, 
>> +  //     -- skipEquals
>> +  // ---------------------------------
>>    SelectFSs<T> at(Annotation fs);  // AI
>>    SelectFSs<T> at(int begin, int end);  // AI
>>    
>> @@ -144,10 +136,10 @@ public interface SelectFSs<T extends Fea
>>    
>>    SelectFSs<T> between(Annotation fs1, Annotation fs2);  // AI implies a coveredBy
style
>>    
>> -  /*********************************
>> -   * terminal operations
>> -   * returning other than SelectFSs
>> -   *********************************/
>> +  // ---------------------------------
>> +  // terminal operations
>> +  // returning other than SelectFSs
>> +  // ---------------------------------
>>    FSIterator<T> fsIterator();
>>    Iterator<T> iterator();
>>    List<T> asList();
>> @@ -155,20 +147,20 @@ public interface SelectFSs<T extends Fea
>>    T get();
>>    T single();
>>    
>> -  /********************************************
>> -   * The methods below are alternatives 
>> -   * to the methods above, that combine
>> -   * frequently used patterns into more
>> -   * concise forms using positional arguments
>> -   ********************************************/
>> -  
>> -  /**
>> -   * Semantics: the arg is used to position.
>> -   * The position is 
>> -   *   - if the arg is a match, then the next/previous one not matching (skip over
matches)
>> -   *     -- uses typePriority, positionUsesType, and skipEqual for match cas
>> -   *   - if the arg is not a match, the first position > or < arg 
>> -   */
>> +  // ---------------------------------
>> +  // The methods below are alternatives 
>> +  // to the methods above, that combine
>> +  // frequently used patterns into more
>> +  // concise forms using positional arguments
>> +  // ---------------------------------
>> +  
>> +  // ---------------------------------
>> +  // Semantics: the arg is used to position.
>> +  // The position is 
>> +  //   - if the arg is a match, then the next/previous one not matching (skip over
matches)
>> +  //     -- uses typePriority, positionUsesType, and skipEqual for match cas
>> +  //   - if the arg is not a match, the first position > or < arg 
>> +  // ---------------------------------
>>    SelectFSs<T> following(Annotation fs);
>>    SelectFSs<T> following(int begin, int end);
>>    SelectFSs<T> following(Annotation fs, int offset);
>>
>>
>>
>


Mime
View raw message