This is an automated email from the ASF dual-hosted git repository. schor pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/uima-uimaj.git
The following commit(s) were added to refs/heads/master by this push: new a9cec9c [UIMA-6153] improve docs for specifying generic types in select framework, fix some typos too a9cec9c is described below commit a9cec9c82819fab09aba43d57a3845ee2dac4f15 Author: Marshall Schor <m...@schor.com> AuthorDate: Wed Dec 4 11:34:20 2019 -0500 [UIMA-6153] improve docs for specifying generic types in select framework, fix some typos too --- .../src/docbook/uv3.select.xml | 63 ++++++++++++++++------ 1 file changed, 46 insertions(+), 17 deletions(-) diff --git a/uima-docbook-v3-users-guide/src/docbook/uv3.select.xml b/uima-docbook-v3-users-guide/src/docbook/uv3.select.xml index 7ab05dd..8d5cb47 100644 --- a/uima-docbook-v3-users-guide/src/docbook/uv3.select.xml +++ b/uima-docbook-v3-users-guide/src/docbook/uv3.select.xml @@ -220,33 +220,62 @@ under the License. <para>There is also a static version of the <code>select</code> method which takes a generically typed index as an argument.</para> + + <para>The best practice is to pass the JCas class representing the type you want, to the select statement. + This enables the generic typing mechanism to be set to that type. In the example below, we use + <code>Token</code> as the type, and <code>fsIterator()</code> just as an example of some terminal form action. + </para> + <informalexample> <?dbfo keep-together="always"?> - <programlisting>// this works + <programlisting>// Best practice, when possible // the generic type for Token is passed as an argument to select FSIterator<Token> token_it = cas.select(Token.class).fsIterator(); +</programlisting> +</informalexample> + + <para>A compile-time generic type can be specified after the select, if the class argument form of <code>select</code> + is not used. In these two examples, the generic type is being specified at compile time, explicitly: </para> + <informalexample> <?dbfo keep-together="always"?> + <programlisting>// ... myCas.select(myType).<Token>fsIterator() ... +// ... myIndexOversomeType.select().<Token>further-operators-of-select-etc +</programlisting> +</informalexample> + + <para>Java 8's type inference doesn't take the generic type past the first object in a build chain, so you can + use these techniques to overcome that. In these examples, tkn_idx is a generically typed variable:</para> + + <informalexample> <?dbfo keep-together="always"?> + <programlisting>FSIndex<Token> tkn_idx = ... ; // generically typed variable +</programlisting> +</informalexample> -FSIndex<Token> token_index = ... ; // generically typed + <para>We show a straight-forward syntax that doesn't work, followed by 3 alternatives that do work.</para> + <informalexample> <?dbfo keep-together="always"?> + <programlisting>// this next fails because the Token generic type from the +// index variable being assigned doesn't get passed to the select(). -// this next fails because the -// Token generic type from the index variable being assigned -// doesn't get passed to the select(). -FSIterator<Token> token_iterator = token_index.select().fsIterator(); +FSIterator<Token> token_iterator = tkn_idx.select().fsIterator(); +</programlisting> +</informalexample> + + <para>You can overcome this in three ways:</para> + + <informalexample> <?dbfo keep-together="always"?> + <programlisting>// pass in the type as an argument to select using the JCas cover type. -// You can overcome this in two ways: -// pass in the type as an argument to select -// using the JCas cover type. FSIterator<Token> token_iterator = - token_index.select(Token.class).fsIterator(); + tkn_idx.select(Token.class).fsIterator(); + +// Or use the static form of select (avoids repeating the type info) -// You can also use the static form of select -// to avoid repeating the type information FSIterator<Token> token_iterator = - SelectFSs.select(token_index).fsIterator(); + SelectFSs.select(tkn_idx).fsIterator(); + +// Or you can also explicitly set the generic type +// that select() should use, like this: -// Finally, you can also explicitly set the generic type -// that select() should use, like a special kind of type cast, like this: FSIterator<Token> token_iterator = - token_index.<Token>select().fsIterator(); + tkn_idx.<Token>select().fsIterator(); </programlisting> </informalexample> @@ -255,7 +284,7 @@ FSIterator<Token> token_iterator = <para>Any specification of an index may be further restricted to just a subType (including that subtype's subtypes, if any) of that index's type. - For example, an AnnotationIndex may be specialized to just Sentences (and their subtypes): + For example, an AnnotationIndex may be specialized to just <code>Token</code>s (and their subtypes): <programlisting>FSIterator<Token> token_iterator = annotation_index.select(Token.class).fsIterator(); </programlisting>