Process
-------

The Process module gathers together interesting geospatial algorithms along with an API
that allows applications to discover what implementations are available at runtime.

Typical Use
^^^^^^^^^^^
While processes can be used directly (you can see how to do that below) the real benefit
is the have a thread pool ready to execute processes in the background.

1. Here is a code example showing creation of a process, and scheduling it to run in a
   thread pool::

    // 3 is one more then the current number of cpu cores
    ProcessExecutor backgroundExecutor = Processors.newProcessExecutor( 3, null );
    
    Process buffer = Processors.createProcess( new NameImpl("gt","buffer") );
    Map<String,Object> input = new KVP("features", inputFeatureCollection, "buffer", 0.01 );
    
    Progress progress = backgroundExecutor.schedule( buffer, input );

2. You can check on the progress of a running process::
    
    if( progress.getProgress() == Progress.WORKING ){
      System.out.println( "Progress: Working");
    else {
      System.out.println( "Progress:"+progress.getProgress() + "percent complete" );
    }

3. To read the value when done::

    Map<String,Object> result = progress.get();
    SimpleFeatureCollection resultFeatureCollection = (SimpleFeatureCollection) result.get("features");

4. If you ask for the value before the progress is complete your current thread will block while the
   value is produced.
   
   This is the Java Future API and represents a thread safe way of calculating something in a
   background thread.

Direct Use
''''''''''

By convention Process implementations have a static helper method that you can call directly.::

    features = RasterToVectorProcess.process( gridCoverage, 2, Collections.EMPTY, null );

For instructions on how to use this method you will need to read the javadocs of the
method in question.

By convention the last parameter is a progress monitor you can use to report back
what is going on to your user - and let them cancel.

Since processes can take minutes to hours this is a good plan.::

    features = RasterToVectorProcess.process( gridCoverage, 2, Collections.EMPTY, monitor );

This is all well and good - what else could happen to make things complicated?

Processors Utility Class
^^^^^^^^^^^^^^^^^^^^^^^^

You can also use the Processors utility class to do things like list all the processes that
are available to be called::

    // find all the process factories and print out their names
    Set<ProcessFactory> processFactories = Processors.getProcessFactories();
    Iterator<ProcessFactory> iterator = processFactories.iterator();
    while (iterator.hasNext()) {
        System.out.println("Process Factory: " + iterator.next().getTitle().toString() );
    }

Setting up A Process
''''''''''''''''''''

You can now create a Process object; and sort out what input it needs::

    Name name = new NameImpl(ProcessFactory.GT_NAMESPACE, "RasterToVectorProcess");
    
    Process r2v = Processors.createProcess(name);
    
    Map<String, Object> params = new HashMap<String, Object>();
    
    params.put(RasterToVectorFactory.RASTER.key, cov);
    params.put(RasterToVectorFactory.BAND.key, Integer.valueOf(0));
    params.put(RasterToVectorFactory.BOUNDS.key, env);
    params.put(RasterToVectorFactory.OUTSIDE.key, Collections.singleton(0.0d));

You can execute your process by hand in the current thread (we are using a swing progress bar
to report progress below).::

    ProgressListener progress = new ProgressWindow(null);
    Map<String, Object> results = r2v.execute(params, progress);

Using a ``ProcessorExecutor``
''''''''''''''''''''''''''''''

The real fun with using the Processes utility class is that you can set up work and then schedule
the work in two separate steps. This is a great way to use multi-core processors in
your application.

1. You can then use a ``ProcessorExecutor`` is going to be in charge of running your processes - you
   can indicate how many threads you want it to keep going at once.
   
   A good idea is the number of cores you have plus 1.::
        
        ProcessExecutor schedule = Processors.newProcessExecutor( 3, null );
        
2. You can then schedule your process - which will produce a Progress - this is a placeholder
   object that you can use to retrieve the answer when it is ready.
   
   You can think of it like a "work ticket".::
    
        Process workTicket = schedule.submit( buffer, input );
    
3. When you want the answer::
       
        Map<String,Object> answer = workTicket.get();

4 The advantage of this technique is that you can get an object that represents the
  activity of doing the work; it will not actually do anything until you need the work done.