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, r...@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); >> >> >> >
