svn commit: r1779061 - /uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml

[sc...@apache.org]

Author: schor
Date: Mon Jan 16 16:35:56 2017
New Revision: 1779061

URL: http://svn.apache.org/viewvc?rev=1779061&view=rev
Log:
[UIMA-5137] add info on migration, maven cookbook

Modified:
    uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml

Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml?rev=1779061&r1=1779060&r2=1779061&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml Mon Jan 16 16:35:56 2017
@@ -27,9 +27,56 @@ under the License.
   <title>Migrating JCas classes from Version 2 to 3</title>
   <titleabbrev>Migrating JCas</titleabbrev>
   
-  <para>To migrate a UIMA application / pipeline to version 3, you need to replace the Version 2 JCas
-	  classes with version 3 classes.
-  </para>
+  <section id="uv3.migration.big_picture">
+    <title>How to migrate an existing UIMA pipeline to V3</title>
+    <titleabbrev>How to migrate</titleabbrev>
+    
+    <para>
+      UIMA V3 is designed to be binary compatible with existing UIMA V2 pipelines, so compiled and/or JAR-ed up classes 
+      representing a V2 pipeline should run with UIMA v3, with two changes:
+      <itemizedlist spacing="compact">
+        <listitem><para>Java 8 is required. (If you're already using Java 8, nothing need be done.)</para></listitem>
+        <listitem><para>Any defined JCas cover classes must be migrated or regenerated, and used instead.
+        (If you do not define any JCas classes or don't use JCas in your pipeline, then nothing need be done.)</para></listitem>
+      </itemizedlist>
+    </para>
+    
+    <para>Some Maven projects use the JCasGen maven plugin; these project's JCasGen maven plugin,
+     if switched to UIMA V3, automatically generate the V3 versions.
+    </para>
+    
+    <para>You can use any of the methods of invoking JCasGen to generate the new V3 versions.  If you already have
+    the source or class files, you can also migrate those using the migration tool described in this section.</para>
+     
+    <para>For simple testing, after users have migrated or generated any user-supplied JCas classes, 
+      users typically will JAR-up these migrated classes,
+      and then place that JAR in the class path ahead of the original V2 pipeline's classes so these will replace
+      the corresponding classes.
+    </para>
+    
+    <section id="uv3.migration.maven-cookbook">
+      <title>How to modify a Maven project to support both v2 and v3</title>
+      <titleabbrev>Maven v2/v3 simultaneous support</titleabbrev>
+      
+      <para>When migrating an existing Maven project to v3, you can of course, just change the dependencies, upgrade
+      to Java 8 if needed, and migrate/regenerate any user-defined JCas class definitions.  Nothing special is needed
+      for this approach.</para>
+      
+      <para>If you want to simultaneously support both v2 and v3, you can take advantage of the binary compatibility
+      support in v3, and have one set of maven artifacts for both (compiled with Java 7), plus an additional
+      Maven project just for the generated JCas classes v3-style.  This additional maven project would 
+      specify Java 8 and UIMA v3 dependencies, and produce a Jar file with the V3 version, either from migrated Java sources,
+      or using the JCasGen maven plugin, generating from the type system description.</para>
+      
+      <para>
+      The using community would see the original output artifacts, plus one new Jar artifact, which, if they were
+      wanting to use V3, they would need to place ahead of the original artifacts in the running pipeline's classpath.
+      </para>
+    </section>
+  </section>
+  <section id="uv3.migration.jcas">
+    <title>Migrating JCas classes</title>
+    
   <para>Some projects are built using Maven, and use the JCasGen Maven plugin as part of the build.
   These builds, when switched to depend on version 3, will automatically generate the new JCas
   class definitions, so nothing special need be done.
@@ -39,6 +86,10 @@ under the License.
 	  as a stand-alone command line tool (<code>runV3migrateJCas.sh or ...bat</code>), or 
 	  as an Eclipse launch configuration.</para>
 	  
+  <para>This tool is run against a directory tree, and scans all the files in the tree, looking for 
+     JCas cover classes.  It can process either source files, or, if those are not available, compiled
+     class files.  It can process these inside directories, as well as inside Jar files within those directories.</para>
+                
 	<para>Run this tool using a Java 8 JDK (as opposed to a Java JRE) in order to have the Java compiler available.</para>
 
   <para>The results of the migration include the migrated class files and a set of logs, summarized in the console
@@ -63,7 +114,8 @@ under the License.
 	  The parts in the source which are version 2 specific with the equivalent
 	  version 3 code.
 	  Only those parts which need updating are modified;
-    other code and comments which are part of the source file are left unchanged.  
+    other code and comments which are part of the source file are left unchanged.  This is intended to preserve
+    any user customization that may have been done.  
     Detailed reports detailing any issues encountered are written to log files. 
   </para>
     
@@ -101,7 +153,9 @@ under the License.
 		    If you run this without any arguments, it will show a brief help for the arguments.
 		  </para>
 		  
-		  <para>There are also a pair of Eclipse launch configuration, which are available if you have the uimaj-examples project
+		  <para>There are also a pair of Eclipse launch configurations 
+        (one for source files, the other for compiled classes), 
+        which are available if you have the uimaj-examples project
         (included in the binary distribution of UIMA) in your Eclipse workspace.
       </para>
       
@@ -384,4 +438,5 @@ In the second prompt,
       conditions found during migration which need manual inspection and fixup.</para>
     </section>
     
+  </section>
 </chapter>
\ No newline at end of file