%% LaTeX Beamer presentation template (requires beamer package)
%% see http://latex-beamer.sourceforge.net/
%% idea contributed by H. Turgut Uyar
%% template based on a template by Till Tantau
%% this template is still evolving - it might differ in future releases!


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%  Uncomment version below for creating normal slides  %%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass[c]{beamer}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\mode<presentation>

\newif\ifsolutions

% Swap this to solutionstrue to include solution slides for the hands-on
% exercises
\solutionstrue
%\solutionsfalse

% Set up an \omitfromhandout command to specify slides that should be omitted
% when generating the handout.
\makeatletter
\newwrite\tf@ofh
\immediate\openout\tf@ofh\jobname.ofh
\makeatother

\newcommand{\omitfromhandout}{\addtocontents{ofh}{\thepage}}

\renewcommand<>{\omitfromhandout}[0]{{\only#1{\beameroriginal{\omitfromhandout}}}}

%\ Make sure the GATE theme is used
\usetheme{GATE}
%\usecolortheme{beaver}
% \setbeamercovered{transparent}
% 
\input{slides-preamble}

\title{The GATE Embedded API}
\subtitle{Module 8, part 1}

% - Use the \inst{?} command only if the authors have different
%   affiliation.
%\author{F.~Author\inst{1} \and S.~Another\inst{2}}
%\author{\inst{1}}

% - Use the \inst command only if there are several affiliations.
% - Keep it simple, no one is interested in your street address.
%\institute{University of Sheffield}

% This is only inserted into the PDF information catalog. Can be left
% out.
\subject{GATE Embedded API}

% If you have a file called "university-logo-filename.xxx", where xxx
% is a graphic format that can be processed by latex or pdflatex,
% resp., then you can add a logo as follows:

%\pgfdeclareimage[height=2cm]{university-logo}{../../images/logo.png}
%\logo{\pgfuseimage{university-logo}}



% Delete this, if you do not want the table of contents to pop up at
% the beginning of each subsection:
\AtBeginSubsection[]
{
\begin{frame}<beamer>
\frametitle{Outline}
\tableofcontents[currentsection, currentsubsection]
\end{frame}
}

% If you wish to uncover everything in a step-wise fashion, uncomment
% the following command:

%\beamerdefaultoverlayspecification{<+->}

\begin{document}

\begin{frame}
\titlepage
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}{Outline}
\tableofcontents
% You might wish to add the option [pausesections]
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{GATE API Basics}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Before We Start}
\begin{block}{Prerequisites}
\begin{itemize}
  \item Java 8 or later JDK (OpenJDK, AdoptJDK, or Oracle)
  \item Java Development Environment such as Eclipse/NetBeans/IDEA (not
    compulsory but {\em highly} recommended!).
  \item Maven 3.6.0 or later -- though hands-on material includes
    \texttt{mvnw}
\end{itemize}
\end{block}
\begin{block}{Hands-on resources}
\begin{itemize}
  \item Download hands-on resources from the participants' wiki
  \item Unzip it somewhere on your hard disk
  \item Have a look at the pom.xml
  \item Import the project into your IDE if you have one
  \item Write a Hello World program to test your configurations
\end{itemize}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Your First GATE-Based Project}
\begin{block}{Libraries to include}
\begin{itemize}
  \item GATE Embedded is distributed via the Central Maven Repository
  \item Group ID \verb!uk.ac.gate!, artifact \verb!gate-core!
  \item Hands-on \verb!pom.xml! has the right dependency already
\end{itemize}
\end{block}
\begin{block}{Documentation}
\begin{itemize}
  \item Various documentation linked from \url{https://gate.ac.uk}
  \item Core JavaDoc at \url{https://javadoc.io/doc/uk.ac.gate/gate-core}
\end{itemize}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{\color{gate-dark-green} Exercise 1: Loading a Document}
\begin{block}{Try this:}
\begin{lstlisting}[texcl]
package module8.part1;
import gate.*;
public class Main {
  public static void main(String[] args)
      throws Exception{
    Gate.init(); // prepare the library
    //create a new document
    Factory.newDocument("This is a document");
  }
}\end{lstlisting}
\end{block}
\begin{block}{Running your code without an IDE:}
\begin{lstlisting}
mvn compile
mvn exec:java -Dexec.mainClass=module8.part1.Main
\end{lstlisting}
\end{block}
\end{frame}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[t]{Interacting with GATE}
\omitfromhandout<1-2>
\begin{block}<1->{Using GATE Developer}
\includegraphics[width= \textwidth]{img/interaction-gui.pdf}
\end{block}
%\pause
\begin{block}<2->{Using GATE API}
\only<2>{\includegraphics[width= \textwidth]{img/interaction-api.pdf}}
\only<3>{\includegraphics[width= \textwidth]{img/interaction-closing-the-loop.pdf}}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Loading a Document (take 2)}
\begin{lstlisting}[texcl]
package module8.part1;
import gate.*;
import gate.gui.*;
import javax.swing.SwingUtilities;

public class Main {
  public static void main(String[] args)
    throws Exception{
    //prepare the library
    Gate.init();
    //show the main window
    SwingUtilities.invokeAndWait(
      () -> MainFrame.getInstance().setVisible(true));
    //create a document
    Factory.newDocument("This is a document");
  }
}
\end{lstlisting}
\end{frame}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{The CREOLE Model}
\subsection{CREOLE Basics}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}{CREOLE}
The GATE component model is called CREOLE ({\bf C}ollection of {\bf RE}usable
{\bf O}bjects for {\bf L}anguage {\bf E}ngineering).

\begin{block}{CREOLE uses the following terminology:}
\begin{itemize}
  \item {\bf CREOLE Plugins}: contain definitions for a set of resources.
  \item {\bf CREOLE Resources}: Java objects with associated configuration.
  \item {\bf CREOLE Configuration}: the metadata associated with Java classes
  that implement CREOLE resources.
\end{itemize}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{CREOLE Plugins}
CREOLE is organised as a set of plugins. 

\begin{block}{Each CREOLE plugin:}
\begin{itemize}
  \item is either
    \begin{itemize}
    \item a directory on disk (or on a web server); with one or more
      \verb!.jar! files of classes, or
    \item a single \verb!.jar! file published to a Maven repository
    \end{itemize}
  \item contains a special file called {\tt creole.xml};
  \item contains the definitions for a set of CREOLE resources.
\end{itemize}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}{CREOLE Resources}
A CREOLE resource is a Java Bean with some additional metadata.
\begin{block}{A CREOLE resource:}
\begin{itemize}
  \item must implement the \lstinline!gate.Resource! interface;
  \item must provide accessor methods for its parameters;
  \item must have associated CREOLE metadata. 
\end{itemize}
\end{block}

\begin{block}{The CREOLE metadata associated with a resource:}
\begin{itemize}
  \item is provided as special Java annotations inside the source code.
\end{itemize}
\end{block}
{\color{red} More details about this later today!}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Resources, Parameters, Features}

\begin{frame}{GATE Resource Types}
\begin{block}{There are three types of resources:}
\begin{itemize}
  \item {\bf Language Resources (LRs)} used to encapsulate data (such as
  documents and corpora);
  \item {\bf Processing Resources (PRs)} used to describe algorithms;
  \item {\bf Visual Resources (VRs)} used to create user interfaces.
\end{itemize}
\end{block}
\begin{block}{The different types of GATE resources relate to each other:}
\begin{itemize}
  \item PRs run over LRs,
  \item VRs display and edit LRs,
  \item VRs manage PRs, \ldots
\end{itemize}
These associations are made via CREOLE configuration.
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{GATE Feature Maps}
\begin{block}{Feature Maps\ldots}
\begin{itemize}
  \item are simply Java Maps, with added support for firing events.
  \item are used to provide parameter values when creating and configuring
  CREOLE resources.
  \item are used to store metadata on many GATE objects.
\end{itemize}
\end{block}
\begin{block}{All GATE resources are feature bearers\\(they implement
\lstinline[style=large]!gate.util.FeatureBearer!):}
\begin{lstlisting}
public interface FeatureBearer{
  public FeatureMap getFeatures();

  public void setFeatures(FeatureMap features);
}
\end{lstlisting}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{FeatureMap Implementation}
\begin{block}{\lstinline[style=large]!gate.FeatureMap!}
\begin{lstlisting}
public interface FeatureMap extends Map<Object, Object>
{
  public void removeFeatureMapListener(
      FeatureMapListener l);
  public void addFeatureMapListener(
    FeatureMapListener l);
}
\end{lstlisting}
\end{block}
\begin{block}{Events: \lstinline[style=large]!gate.event.FeatureMapListener!}
\begin{lstlisting}
public interface FeatureMapListener 
    extends EventListener
{
  public void featureMapUpdated();
}
\end{lstlisting}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}{Resource Parameters}
The behaviour of GATE resources can be affected by the use of parameters.

\begin{block}{Parameter values:}
\begin{itemize}
  \item are provided as populated feature maps.
  \item can be any Java Object;
  \item This includes GATE resources! 
\end{itemize}
\end{block} 
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}{Parameter Types}
There are two types of parameters: 
\begin{block}{Init-time Parameters}
\begin{itemize}
  \item Are used during the instantiating resources.
  \item Are available for all resource types. 
  \item Once set, they cannot be changed.
\end{itemize}
\end{block}
\begin{block}{Run-time Parameters}
\begin{itemize}
  \item are only avaialable for Processing Resources.
  \item are set before executing the resource, and are used to affect the 
behaviour of the PR.
 \item can be changed between consecutive runs.
\end{itemize}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Creating a GATE Resource}
Always use the GATE Factory to create and delete GATE resources!
\begin{block}{\lstinline[style=large]!gate.Factory!}
\begin{lstlisting}
public static Resource createResource(
  String resourceClassName, 
  FeatureMap parameterValues,
  FeatureMap features, 
  String resourceName){
  ...
}    
\end{lstlisting}
\end{block}
Only the first parameter is required; other variants of this method are
available, which require fewer parameters.
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Creating a GATE Resource}
\begin{block}{You will need the following values:}
\begin{itemize}
  \item \lstinline[style=large]!String resourceClassName!: the class name for
  the resource you are trying to create. This should be a string with the fully-qualified class
  name, e.g. \lstinline[style=large]!"gate.corpora.DocumentImpl"!.
  \item \lstinline[style=large]!FeatureMap parameterValues!: the values for the
  init-time parameters. Parameters that are not specified will get their default values
  (as described in the CREOLE configuration). It is an error for a required
  parameter not to receive a value (either explicit or default)!
  \item \lstinline[style=large]!FeatureMap features!: the initial values for the new resource's
  features.
  \item \lstinline[style=large]!String resourceName!: the name for the new
  resource.
\end{itemize}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Example: Load a Document (take 3)}
\begin{lstlisting}[texcl]
FeatureMap params = Factory.newFeatureMap();
params.put(
    Document.DOCUMENT_STRING_CONTENT_PARAMETER_NAME, 
    "This is a document!");
FeatureMap feats = Utils.featureMap(
    "createdBy", "me!");
Factory.createResource("gate.corpora.DocumentImpl", 
    params, feats, "My first document");
\end{lstlisting}
\begin{block}{\color{red}TIP: Resource Parameters}
The easiest way to find out what parameters resources take (and which ones are
required, and what types of values they accept) is to use the GATE Developer UI
and try to create the desired type of resource in the GUI! 
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Aside: Creating a FeatureMap}
\begin{itemize}
\item You can create an empty feature map with \lstinline!Factory.newFeatureMap()!
  and use the normal \lstinline!put! method to add entries.
\item \lstinline!gate.Utils.featureMap! is a shortcut to create a populated map
  \begin{itemize}
  \item takes an alternating list of key1, value1, key2, value2, \ldots
  \end{itemize}
\end{itemize}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Example: Load a Document (take 3)}
\includegraphics[width=270px]{img/take3.png}
\end{frame}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Shortcuts for Loading GATE Resources}
\begin{block}{Loading a GATE {\bf document}}
\begin{lstlisting}[texcl]
import gate.*;
//create a document from a String content
Document doc = Factory.newDocument("Document text");
//\ldots or a URL
doc = Factory.newDocument(new URL("https://gate.ac.uk"));
//\ldots or a URL and a specified encoding
doc = Factory.newDocument(new URL("https://gate.ac.uk"),
    "UTF-8");
\end{lstlisting}
\end{block}
\begin{block}{Loading a GATE {\bf corpus}}
\begin{lstlisting}
Corpus corpus = Factory.newCorpus("Corpus Name");
\end{lstlisting}
\end{block}

\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[t]{\color{gate-dark-green} Exercise 2: Loading a Document
(again!)}
\begin{block}{Load a document:}
\begin{itemize}
  \item using the GATE home page as a source;
  \item using the UTF-8 encoding;
  \item having the name ``This is home'';
  \item having a feature named {\tt "date"}, with the value the current
  date.
\end{itemize}
{\color{red} TIP:} Make sure the GATE Developer main window is shown to test the
results!
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Annotations, Documents, Corpora}

\begin{frame}{GATE Documents}
\begin{block}{A GATE Document comprises:}
\begin{itemize}
  \item a DocumentContent object;
  \item a Default annotation set (which has no name);
  \item zero or more named annotation sets;
\end{itemize}
\end{block}
\begin{block}{A Document is also a type of Resource, so it also has:}
\begin{itemize}
  \item a name;
  \item features.
\end{itemize}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Main Document API Calls}
\begin{lstlisting}[texcl]
// Obtain the document content
public DocumentContent getContent();
// Get the default annotation set. 
public AnnotationSet getAnnotations();
// Get a named annotation set.
public AnnotationSet getAnnotations(String name);
// Get the names for the annotation sets.
public Set<String> getAnnotationSetNames();
// Get all named annotation sets.
public Map<String, AnnotationSet> 
  getNamedAnnotationSets();
// Convert to GATE stand-off XML
public String toXml();
// Convert some annotations to inline XML.  
public String toXml(Set aSourceAnnotationSet, 
  boolean includeFeatures);
\end{lstlisting}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Annotation Sets}
\begin{block}{GATE Annotation Sets\ldots}
\begin{itemize}
  \item maintain a set of \lstinline[style=large]!Node! objects (which are associated with
  offsets in the document content);
  \item and a set of annotations (which have a start and an end node).
  \item implement the \lstinline[style=large]!gate.AnnotationSet! interface;
  \item \ldots which extends \lstinline[style=large]!Set<Annotation>!.
  \item implement several \lstinline[style=large]!get()! methods for obtaining the included
  annotations according to various constraints.
  \item are created, deleted, and managed by the Document they belong to.
\end{itemize}
\end{block}
{\color{red}TIP:} always use a Document object to create a new annotation set!
Do not use the constructor!
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Main AnnotationSet API Calls}
\begin{block}{Nodes}
\begin{lstlisting}[texcl]
// Get the node with the smallest offset.
public Node firstNode();
// Get the node with the largest offset.
public Node lastNode();
\end{lstlisting}
\end{block}
\begin{block}{Creating new Annotations}
\begin{lstlisting}[texcl]
// Create (and add) a new annotation
public Integer add(Long start, Long end, 
    String type, FeatureMap features);
// Create (and add) a new annotation
public Integer add(Node start, Node end, 
    String type, FeatureMap features)
\end{lstlisting}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{AnnotationSet API (continued)}
\begin{block}{Getting Annotations by ID, or type}
\begin{lstlisting}[texcl]
// Get annotation by ID
public Annotation get(Integer id);
// Get all annotations of one type
public AnnotationSet get(String type)
// Get all annotation types present
public Set<String> getAllTypes()
// Get all annotations of specified types
public AnnotationSet get(Set<String> types)
\end{lstlisting}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{AnnotationSet API (continued)}
\begin{block}{Getting Annotations by position}
\begin{lstlisting}[texcl]
// Get all annotations starting at a given 
// location, or right after.
public AnnotationSet get(Long offset)
// Get all annotations that overlap an interval 
public AnnotationSet get(Long startOffset, 
    Long endOffset)
// Get all annotations within an interval.
public AnnotationSet getContained(Long startOffset, 
    Long endOffset)
// Get all annotations covering an interval.    
public AnnotationSet getCovering(String neededType, 
    Long startOffset, Long endOffset)
\end{lstlisting}
\end{block}
Many of these have more convenient forms available via static methods of
\href{https://javadoc.io/page/uk.ac.gate/gate-core/latest/gate/Utils.html}{\lstinline!gate.Utils!}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{AnnotationSet API (continued)}
\begin{block}{Combined get methods}
\begin{lstlisting}[texcl]
// Get by type and feature constraints.
public AnnotationSet get(String type,
    FeatureMap constraints)
// Get by type, constraints and start position.    
public AnnotationSet get(String type, 
    FeatureMap constraints, Long offset)
// Get by type, and interval overlap. 
public AnnotationSet get(String type, 
    Long startOffset, Long endOffset)
// Get by type and feature presence
public AnnotationSet get(String type, 
    Set featureNames)
\end{lstlisting}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[t]{\color{gate-dark-green} Exercise 3: The AnnotationSet API}
\begin{block}{For the document loaded in excercise 2:}
\begin{itemize}
  \item find out how many named annotation sets it has;
  \item find out how many annotations each set contains;
  \item for each annotation set, for each annotation type, find out how many
  annotations are present.
\end{itemize}
{\color{red} TIP:} Make sure the GATE Developer main window is shown to test
the results!
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Annotations}
\begin{block}{GATE Annotations\ldots}
\begin{itemize}
  \item are metadata associated with a document segment;
  \item have a type (\lstinline[style=large]!String!);
  \item have a start and an end Node (\lstinline[style=large]!gate.Node!);
  \item have features;
  \item are created, deleted and managed by annotation sets.
\end{itemize}
\end{block}
{\color{red}TIP:} always use an annotation set to create a new annotation! Do
not use the constructor.
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Annotation API}
\begin{block}{Main Annotation methods:}
\begin{lstlisting}[texcl]
  public String getType();
  public Node getStartNode();
  public Node getEndNode();
  public FeatureMap getFeatures();
\end{lstlisting}
\end{block}
\begin{block}{\lstinline[style=large]!gate.Node!}
\begin{lstlisting}
public Long getOffset();
\end{lstlisting}
\end{block}
Again \lstinline!gate.Utils! has convenient shortcuts for start and end
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile, t]{\color{gate-dark-green} Exercise 4: Annotation API}
\begin{block}{Implement the following:}
\begin{itemize}
  \item Use the document created in exercise 3;
  \item Use the annotation set \lstinline[style=large]!Original markups! and 
        obtain annotations of type \lstinline[style=large]!a! (anchor).
  \item Iterate over each annotation, obtain its features and print the value of
        \lstinline[style=large]!href! feature.
\end{itemize}
\end{block}
{\color{red}TIP:} For Java experts -- before printing the value of
\lstinline[style=large]!href!  feature, use the
\lstinline[style=large]!new URL(URL context, String spec)!  constuctor such
that the value of the \lstinline[style=large]!href! feature is parsed within
the context of the document's source url.
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Execution Control}
\subsection{Processing Resources and Language Analysers}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{GATE Processing Resources}
Processing Resources ({\bf PRs}) are java classes that can be executed.
\begin{block}{\lstinline[style=large]!gate.Executable!}
\begin{lstlisting}[texcl]
public interface Executable {
  public void execute() throws ExecutionException;
  public void interrupt();
  public boolean isInterrupted();
}
\end{lstlisting}
\end{block}

\begin{block}{\lstinline[style=large]!gate.ProcessingResource!}
\begin{lstlisting}[texcl]
public interface ProcessingResource 
  extends Resource, Executable
{
  public void reInit() 
    throws ResourceInstantiationException;
}
\end{lstlisting}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Language Analysers}
Analysers are PRs that are designed to run over the documents in a corpus.
\begin{lstlisting}[texcl]
public interface LanguageAnalyser 
    extends ProcessingResource {
    
  // Set the document property for this analyser.
  public void setDocument(Document document);

  // Get the document property for this analyser.
  public Document getDocument();

  // Set the corpus property for this analyser.
  public void setCorpus(Corpus corpus);

  // Get the corpus property for this analyser.
  public Corpus getCorpus();
}
\end{lstlisting}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Loading a CREOLE Plugin}
\begin{itemize}
  \item Documents and corpora are built in resource types.
  \item All other CREOLE resources are defined as plugins.
  \item Before instantiating a resource, you need to load its CREOLE plugin
  first!
  \item Use \verb!registerPlugin! method on the \verb!CreoleRegister!
  \item Standard GATE plugins are referenced by Maven coordinates, and
    downloaded automatically by GATE
\end{itemize}
\begin{block}{Loading a CREOLE plugin}
\begin{lstlisting}[texcl,basicstyle=\scriptsize\ttfamily]
//load the tools plugin.
Gate.getCreoleRegister().registerPlugin(
  new Plugin.Maven("uk.ac.gate.plugins", "tools", "8.6"));
\end{lstlisting}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile, t]{\color{gate-dark-green} Exercise 5: Run a Tokeniser}
\begin{block}{Implement the following:}
\begin{itemize}
  \item Load the ``annie'' plugin, version 8.6
  \item Instantiate a Language Analyser of type
  \lstinline[style=large]!gate.creole.tokeniser.DefaultTokeniser! (using the default values
  for all parameters);
  \item set the \lstinline[style=large]!document! of the tokeniser to the document created in
  exercise 2;
  \item set the \lstinline[style=large]!corpus! of the tokeniser to \lstinline[style=large]!null!;
  \item call the \lstinline[style=large]!execute()! method of the tokeniser;
  \item inspect the document and see what the results were.  
\end{itemize}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Controllers}
\begin{frame}[fragile]{GATE Controllers}
\begin{itemize}
  \item Controllers provide the implementation for execution control in GATE.
  \item They are called {\it applications} in GATE Developer.
  \item The implementations provided by default implement a {\it pipeline}
  architecture (they run a set of PRs one after another).
  \item Other kind of implementations are also possible.
    \begin{itemize}
    \item e.g. the Groovy plugin provides a \emph{scriptable} controller
    implementation
    \end{itemize}
  \item A controller is a class that implements 
  \lstinline[style=large]!gate.Controller!.
\end{itemize}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Implementation}
\begin{block}{\lstinline[style=large]!gate.Controller!}
\begin{lstlisting}[texcl]
public interface Controller extends Resource, 
    Executable, NameBearer, FeatureBearer {
  public Collection getPRs();
  public void setPRs(Collection PRs);
  public void execute() throws ExecutionException;
} 
\end{lstlisting}
\end{block}
\begin{itemize}
  \item all default controller implementations also implement
  \lstinline[style=large]!gate.ProcessingResource! (so you can include controllers inside
  other controllers!);
  \item like all GATE resources, controllers are created using the
  \lstinline[style=large]!Factory! class;
  \item controllers have names, and features.
\end{itemize}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Default Controller Types}
The following default controller implementations are provided (all in the
\lstinline[style=large]!gate.creole! package):
\begin{itemize}
  \item \lstinline[style=large]!SerialController!: a pipeline of PRs.
  \item \lstinline[style=large]!ConditionalSerialController!: a pipeline of
  PRs. Each PR has an associated \lstinline[style=large]!RunningStrategy! value
  which can be used to decide {\bf at runtime} whether or not to run the PR.
  \item \lstinline[style=large]!SerialAnalyserController!: a pipeline of
  \lstinline[style=large]!LanguageAnalyser!s, which runs all the PRs over all
  the documents in a \lstinline[style=large]!Corpus!. The
  \lstinline[style=large]!corpus! and \lstinline[style=large]!document!
  parameters for each PR are set by the controller.
  \item \lstinline[style=large]!RealtimeCorpusController!: a version of
  \lstinline[style=large]!SerialAnalyserController! that interrupts the
  execution over a document when a specified timeout has lapsed.
\end{itemize}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{SerialAnalyserController API}
\lstinline[style=large]!SerialAnalyserController! is the most used type of
Controller. Its most important methods are:
\begin{lstlisting}[texcl]
  // Adds a new PR at a given position
  public void add(int index, ProcessingResource pr);
  // Adds a new PR at the end
  public void add(ProcessingResource pr);
  // Replaces the PR at a given position
  public ProcessingResource set(int index, 
      ProcessingResource pr);  
  // Remove a PRs by position
  public ProcessingResource remove(int index);
  // Remove a specified PR
  public boolean remove(ProcessingResource pr);
  // Sets the corpus to be processed
  public void setCorpus(gate.Corpus corpus);  
  // Runs the controller
  public void execute() throws ExecutionException;  
\end{lstlisting}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile,t]{\color{gate-dark-green} Exercise 6: Run a Tokeniser
(again!)}
\begin{block}{Implement the following:}
\begin{itemize}
  \item Create a SerialAnalyserController, and add the tokeniser from exercise
  5 to it;
  \item Create a corpus, and add the document from exercise 2 to it;
  \item Set the \lstinline[style=large]!corpus! value of the controller to the newly created
  corpus;
  \item Execute the controller;
  \item Inspect the results.
\end{itemize}
\end{block}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Controller Persistency (or {\it Saving Applications})}
\begin{itemize}
  \item The configuration of a controller (i.e. the list of plugins loaded, the
  list of PRs included, as well as the features and parameter values for the
  controller and its PRs) can be saved using a special type of XML
  serialisation.
  \item This is done using the
  \lstinline[style=large]!gate.util.persistence.PersistenceManager! class.
  \item This is what {\em GATE Developer} does when saving and loading
  applications.
  \item In most cases this is the best way to work when using GATE Embedded
  \begin{itemize}
    \item Build your application in GATE Developer, save state
    \item Load the saved app in your code with \lstinline[style=large]!PersistenceManager!
  \end{itemize}
\end{itemize}

\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{frame}[fragile]{Implementation}
\begin{block}{\lstinline[style=large]!gate.util.persistence.PersistenceManager!}
\begin{lstlisting}[texcl]
// Serialises the configuration of a GATE object 
// to a special XML format.
public static void saveObjectToFile(Object obj, 
    File file) throws PersistenceException, 
    IOException ;
      
// Re-creates the serialised GATE object from the saved
// configuration data.
public static Object loadObjectFromFile(File file)
    throws PersistenceException, IOException,
    ResourceInstantiationException;
// Loads a GATE object from a location which can be a file, remote URL,
// or inside a plugin JAR (creole://group;artifact;version/path.xgapp)
public static Object loadObjectFromUri(URI uri) 
  throws PersistenceException, IOException, 
  ResourceInstantiationException, URISyntaxException;           
\end{lstlisting}
\end{block}
\end{frame}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section*{}

\begin{frame}[c]
\begin{block}{\Huge Thank you!}
\end{block}
\begin{block}{\Huge \color{gate-light-red} Questions?}
\end{block}

\begin{block}{More answers at:}
\large
\begin{itemize}
  \item \url{https://gate.ac.uk} (Our website)
  \item \url{https://gate.ac.uk/mail/} (Our mailing list)
\end{itemize}
\end{block}
\end{frame}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Solution here
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ifsolutions
\addtocounter{framenumber}{-3}\framenumbersfalse


%%%%% Exercise 2

\begin{frame}[fragile]
\omitfromhandout
\frametitle{\color{gate-dark-green} Exercise 2: Solution}
A possible solution
\begin{lstlisting}[texcl,basicstyle=\scriptsize\ttfamily]
import gate.*;
import java.net.URL;
import java.util.Date;
import javax.swing.SwingUtilities;

public class Main {
  public static void main(String[] args) 
      throws Exception{

    // prepare the library
    Gate.init();
    // show the main window
    SwingUtilities.invokeAndWait(
      () -> MainFrame.getInstance().setVisible(true));

\end{lstlisting}
\end{frame}

\begin{frame}[fragile]
\omitfromhandout
\frametitle{\color{gate-dark-green} Exercise 2: Solution (continued)}
\begin{lstlisting}[firstnumber=last,texcl,basicstyle=\scriptsize\ttfamily]
    // init-time parameter for document
    FeatureMap params = Factory.newFeatureMap();
    params.put(Document.DOCUMENT_URL_PARAMETER_NAME, 
      new URL("https://www.gate.ac.uk"));

    params.put(Document.DOCUMENT_ENCODING_PARAMETER_NAME, 
      "UTF-8");

    // document features
    FeatureMap feats = Factory.newFeatureMap();
    feats.put("date", new Date());
    Factory.createResource("gate.corpora.DocumentImpl", 
      params, feats, "This is home");
  }
}
\end{lstlisting}
\end{frame}

\begin{frame}[fragile]
\omitfromhandout
\frametitle{\color{gate-dark-green} Exercise 2: Solution (continued)}
\includegraphics[width=290px]{img/ex2-result.png}
\end{frame}


%%%%% Exercise 3

\begin{frame}[fragile]
\omitfromhandout
\frametitle{\color{gate-dark-green} Exercise 3: Solution}
Additions to the solution of Exercise 2
\begin{lstlisting}[texcl,basicstyle=\scriptsize\ttfamily]
    ...
    
   // obtain a map of all named annotation sets
   Map<String, AnnotationSet> namedASes = 
     doc.getNamedAnnotationSets();
   System.out.println("No. of named Annotation Sets:" 
     + namedASes.size());

   // no of annotations each set contains
   namedASes.forEach((setName, aSet) -> {
     // no of annotations
     System.out.println("No. of Annotations for " + 
       setName + ":" + aSet.size());

\end{lstlisting}
\end{frame}

\begin{frame}[fragile]
\omitfromhandout
\frametitle{\color{gate-dark-green} Exercise 3: Solution (Continued..)}
\begin{lstlisting}[firstnumber=last,texcl,basicstyle=\scriptsize\ttfamily]
     // all annotation types
     Set<String> annotTypes = aSet.getAllTypes();
     for(String aType : annotTypes) {
       System.out.println("  " + aType + ": " 
         + aSet.get(aType).size());
     }
   }
   
   ...
\end{lstlisting}
\end{frame}


\begin{frame}[fragile]
\omitfromhandout
\frametitle{\color{gate-dark-green} Exercise 3: Solution (continued)}
\includegraphics[width=290px]{img/ex3-result.png}
\end{frame}

%%%%% Exercise 4

\begin{frame}[fragile]
\omitfromhandout
\frametitle{\color{gate-dark-green} Exercise 4: Solution}
Additions to the solution of Exercise 2
\begin{lstlisting}[texcl,basicstyle=\scriptsize\ttfamily]
    ...
    
   // obtain the Original markups annotation set
   AnnotationSet origMarkupsSet = 
     doc.getAnnotations("Original markups");

   // obtain annotations of type 'a'
   AnnotationSet anchorSet = origMarkupsSet.get("a");
   
   // iterate over each annotation
   // obtain its features and print the value of href feature
   for (Annotation anchor : anchorSet) {
     String href = (String) anchor.getFeatures().get("href");
     if(href != null) {
       // resolving href value against the document's url
       System.out.println(new URL(doc.getSourceUrl(), href));
     }
   }
   
   ...
\end{lstlisting}
\end{frame}

\begin{frame}[fragile]
\omitfromhandout
\frametitle{\color{gate-dark-green} Exercise 4: Solution (continued)}
\includegraphics[width=290px]{img/ex4-result.png}
\end{frame}

%%%%% Exercise 5

\begin{frame}[fragile]
\omitfromhandout
\frametitle{\color{gate-dark-green} Exercise 5: Solution}
Additions to the solution of Exercise 2
\begin{lstlisting}[texcl,basicstyle=\scriptsize\ttfamily]
    ...
    
    //Let's load the ANNIE plugin
    Gate.getCreoleRegister().registerPlugin(
      new Plugin.Maven("uk.ac.gate.plugins", "annie", "8.6"));

    // create tokenizer
    LanguageAnalyser pr = (LanguageAnalyser) 
      Factory.createResource(
        "gate.creole.tokeniser.DefaultTokeniser");
		
    pr.setDocument(doc); // set the document
    pr.setCorpus(null); // set the corpus to null
    pr.execute(); // execute the PR
   
    ...
\end{lstlisting}
\end{frame}

\begin{frame}[fragile]
\omitfromhandout
\frametitle{\color{gate-dark-green} Exercise 5: Solution (continued)}
\includegraphics[width=290px]{img/ex5-result.png}
\end{frame}

%%%%% Exercise 6

\begin{frame}[fragile]
\omitfromhandout
\frametitle{\color{gate-dark-green} Exercise 6: Solution}
Additions to the solution of Exercise 2
\begin{lstlisting}[texcl,basicstyle=\scriptsize\ttfamily]
    ...
    
    //Let's load the ANNIE plugin
    Gate.getCreoleRegister().registerPlugin(
      new Plugin.Maven("uk.ac.gate.plugins", "annie", "8.6"));

    // create tokenizer
    LanguageAnalyser pr = (LanguageAnalyser) 
      Factory.createResource(
        "gate.creole.tokeniser.DefaultTokeniser");
		  
\end{lstlisting}
\end{frame}

\begin{frame}[fragile]
\omitfromhandout
\frametitle{\color{gate-dark-green} Exercise 6: Solution (Continued..)}
\begin{lstlisting}[firstnumber=last,texcl,basicstyle=\scriptsize\ttfamily]

    // create serialAnalyzerController
    SerialAnalyserController controller = 
      (SerialAnalyserController) Factory.createResource(
         "gate.creole.SerialAnalyserController");
    // add pr to the corpus
    controller.add(pr);
		
    // create a corpus 
    Corpus corpus = Factory.newCorpus("corpus");
    corpus.add(doc); // add document to the corpus
    controller.setCorpus(corpus); // set corpus 
    controller.execute(); // execute the corpus
   
   ...
\end{lstlisting}
\end{frame}


\begin{frame}[fragile]
\omitfromhandout
\frametitle{\color{gate-dark-green} Exercise 6: Solution (continued)}
\includegraphics[width=290px]{img/ex6-result.png}
\end{frame}


\framenumberstrue
\fi

%%%%%%%%%%%%%%%%%%
\end{document}
