// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership. The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the License for the
// specific language governing permissions and limitations
// under the License.

[[ugr.tools.eclipse_launcher]]
= Eclipse Analysis Engine Launcher's Guide
// <titleabbrev>Eclipse Analysis Engine Launcher's Guide</titleabbrev>

The Analysis Engine Launcher is an Eclipse plug-in that provides debug and run support  for Analysis Engines directly within eclipse, like a Java program can be debugged.
It supports most of the descriptor formats except CPE, UIMA AS and some remote deployment descriptors. 


image::images/tools/tools.eclipse_launcher/image01.png[]


[[ugr.tools.eclipse_launcher.create_configuration]]
== Creating an Analysis Engine launch configuration

To debug or run an Analysis Engine a launch configuration must be created.
To do this select "Run -> Run Configurations" or "Run -> Run Configurations" from the menu bar.
A dialog will open where the launch configuration can be created.
Select UIMA Analysis Engine and create a new configuration via pressing the New button at the top, or via the New button in the context menu.
The newly created configuration will be automatically selected and the Main tab will be displayed. 

The Main tab defines the Analysis Engine which will be launched.
First select the project which contains the descriptor, then choose a descriptor and select the input.
The input can either be a folder which contains input files or just a single input file, if the recursively check box is marked the input folder will be scanned recursively for input files. 

The input format defines the format of the input files, if it is set to CASes the input resource must be either in the XMI or XCAS format and if it is set to plain text, plain text input files in the specified encoding are expected.
The input logic filters out all files which do not have an appropriate file ending, depending on the chosen format the file ending must be one of .xcas, .xmi or .txt, all other files are ignored when the input is a folder, if a single file is selected it will be processed independent of the file ending. 

The output directory is optional, if set all processed input files will be written to the specified directory in the XMI CAS format, if the clear check box is marked all files inside the output folder will be deleted, usually this option is not needed because existing files will be overwritten without notice. 

The other tabs in the launch configuration are documented in the eclipse documentation, see the "Java development user guide -> Tasks -> Running and Debugging". 

[[ugr.tools.eclipse_launcher.launching]]
== Launching an Analysis Engine

To launch an Analysis Engine go to the previously created launch configuration and click on "Debug" or "Run" depending on the desired run mode.
The Analysis Engine will now be launched.
The output will be shown in the Console View.
To debug an Analysis Engine place breakpoints inside the implementation class.
If a breakpoint is hit the execution will pause  like in a Java program. 