%% 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>

% 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}
\input{slides-preamble}
\setbeamerfont{alerted text}{series=\bfseries}

\title{Creating new Resource Types}
\subtitle{Track II, Module 7}

% - 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{Creating new Resource Types}

% 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
\end{frame}

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

\section{CREOLE Basics}
\subsection{CREOLE Recap}


\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}{CREOLE Plugins}
CREOLE is organised as a set of plugins. 

\begin{block}{Each CREOLE plugin:}
\begin{itemize}
  \item is a directory on disk (or on a web server);
  \item is specified as a URL pointing to the {\bf directory};
  \item contains a special file called {\tt creole.xml};
  \item may contain one or more .jar files with compiled Java classes.
  \begin{itemize}
    \item alternatively, the required Java classes may simply be placed on the
    application classpath.
  \end{itemize}
  \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 can be provided inside the {\tt creole.xml} file for the plugin;
  \item can be provided as special Java annotations inside the source code
  (recommended).
\end{itemize}
\end{block}
\end{frame}

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

\subsection{CREOLE Metadata}

\begin{frame}[fragile,t]{Structure of a creole.xml File}
\omitfromhandout<1-5>
\begin{columns}
\column{0.46\textwidth}
\begin{lstlisting}[language=XML, basicstyle=\scriptsize\ttfamily, escapechar=|]
|\alert<2>{<CREOLE-DIRECTORY>}|
 |\alert<3>{<CREOLE>}|
   |\alert<4>{<JAR>jarfile1.jar</JAR>}|
   |\alert<4>{<JAR>jarfile2.jar</JAR>}|
   ...
   |\alert<5>{<RESOURCE>...</RESOURCE>}|
   |\alert<5>{<RESOURCE>...</RESOURCE>}|
   |\alert<5>{<RESOURCE>...</RESOURCE>}|
   ...
 |\alert<3>{</CREOLE>}|
 |\alert<3>{<CREOLE>...</CREOLE>}|
 |\alert<3>{<CREOLE>...</CREOLE>}|
 ...
</CREOLE-DIRECTORY>
\end{lstlisting}
\column{0.50\textwidth}
Each {\tt creole.xml} file contains:
\begin{itemize}
  \item <2-> one CREOLE-DIRECTORY element, containing:
  \item <3-> optionally, zero or more CREOLE elements (used for grouping);
  \item <4-> optionally, zero or more JAR elements;
  \item <5-6> one or more RESOURCE elements.
\end{itemize}
\end{columns}

\end{frame}

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

\begin{frame}[fragile]{A creole.xml Example}
\begin{lstlisting}[language=XML, basicstyle=\scriptsize\ttfamily]
...
<RESOURCE>
 <NAME>ANNIE VP Chunker</NAME>
 <CLASS>gate.creole.VPChunker</CLASS>
 <COMMENT>ANNIE VP Chunker component.</COMMENT>
 <HELPURL>http://gate...sec:parsers:vgchunker</HELPURL>
 <PARAMETER NAME="document" RUNTIME="true"
    COMMENT="The document to be processed">
    gate.Document</PARAMETER>
  <PARAMETER NAME="inputASName" RUNTIME="true"
    COMMENT=
    "The annotation set to be used as input"
    OPTIONAL="true">java.lang.String</PARAMETER>
  <PARAMETER NAME="outputASName" RUNTIME="true"
    COMMENT=
    "The annotation set to be used as output"
    OPTIONAL="true">java.lang.String</PARAMETER>
...
</RESOURCE>\end{lstlisting}
\begin{block}{More info: http://gate.ac.uk/userguide/sec:creole-model:config}
\end{block}
\end{frame}

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

\section{Creating CREOLE Resources}

\subsection{Your First Language Analyser}

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

\begin{frame}{A CREOLE Resource}
To create a new CREOLE resource type, you need:
\begin{itemize}
  \item A Java class that implements the \lstinline[style=large]!gate.Resource!
  interface, or one of its sub-interfaces: 
  \begin{itemize}
    \item \lstinline[style=large]!gate.LanguageResource!
    \item \lstinline[style=large]!gate.ProcessingResource!
    \item \lstinline[style=large]!gate.VisualResource!
    \item \lstinline[style=large]!gate.Controller!
  \end{itemize}
  \item  a directory containing:
  \begin{itemize}
    \item a creole.xml file.
    \item a .jar file with the compiled Java class.
  \end{itemize}
\end{itemize}
\end{frame}

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

\begin{frame}[fragile, t]{\color{gate-dark-green} Exercise 1: Create an Empty
Processing Resource}
\begin{block}{Create a Java class:}
\begin{lstlisting}[basicstyle=\scriptsize\ttfamily]
package module7;
import gate.creole.AbstractLanguageAnalyser;
public class DocStats extends AbstractLanguageAnalyser { }
\end{lstlisting}
\end{block}
\begin{itemize}
  \item make sure it compiles;
  \item create a .jar file with the compiled class;
  \item {\color{gate-light-green} TIP:} see the {\tt build.xml} file in your
  hands-on!
\end{itemize}
\begin{block}{Create a corresponding creole.xml file:}
\begin{lstlisting}[language=XML, basicstyle=\scriptsize\ttfamily]
<CREOLE-DIRECTORY><CREOLE>
  <RESOURCE>
    <NAME>Document Statistics</NAME>
    <CLASS>module7.DocStats</CLASS>
  </RESOURCE>
</CREOLE></CREOLE-DIRECTORY>
\end{lstlisting}
\end{block}
\end{frame}


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

\begin{frame}[fragile, t]{\color{gate-dark-green} Exercise 1 (part 2):
Implementation}
\begin{block}{Implement:}
\begin{lstlisting}
public Resource init() 
  throws ResourceInstantiationException { }
\end{lstlisting}
\ldots to print out a message;
\end{block}
\begin{block}{Implement:}
\begin{lstlisting}
public void execute() throws ExecutionException { }
\end{lstlisting}
\ldots to count the number of Token annotations in the input document, and set
the value as a feature on the document.
\end{block}
\end{frame}

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

\begin{frame}[fragile, t]{\color{gate-dark-green} Exercise 1: Solution}
\omitfromhandout<1>
{\color{gate-light-red} Try not to use this!}
\pause
\begin{lstlisting}[basicstyle=\tiny\ttfamily]
package module7;

import gate.Resource;
import gate.creole.AbstractLanguageAnalyser;
import gate.creole.ExecutionException;
import gate.creole.ResourceInstantiationException;

public class DocStats extends AbstractLanguageAnalyser {

  @Override
  public void execute() throws ExecutionException {
    int tokens = document.getAnnotations().get("Token").size(); 
    document.getFeatures().put("token_count", tokens);
  }

  @Override
  public Resource init() throws ResourceInstantiationException {
    System.out.println(getClass().getName() + " is initialising.");
    return this;
  }
}
\end{lstlisting}
\end{frame}

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

\subsection{Best Practice}

\begin{frame}{Best Practice: Use Parameters!}
\begin{itemize}
  \item Do not hardcode values, specify them as parameters.
  \item Values that change internal data structures, built when the PR is
  created, should be {\tt init-time} parameters. These cannot be changed once
  the PR was created.
  \item Values that can be changed between executions should be {\tt run-time}
  parameters.
  \item Try to make as many parameters as possible into {\tt run-time}
  parameters!
  \item Provide {\em sensible defaults} for most parameters.
  \item If you have too many init-time parameters, use a config file instead!
  \item If you have too many run-time parameters, provide a Visual Resource!
  \item Make sure the parameters are well documented in the creole.xml file! 
\end{itemize}
\end{frame}

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

\begin{frame}{Best Practice: Input/Output}
\begin{block}{Specify Input/Output!}
\begin{itemize}
  \item If your PR uses annotations, always specify input and output
  annotation sets:
  \item use a parameter {\tt inputASName} for the input annotation set name;
  \item use a parameter {\tt outputASName} for the output annotation set name;
\end{itemize}
{\bf OR}
\begin{itemize}
  \item use a parameter named {\tt annotationSetName} (if the PR only
  modifies existing annotations).
\end{itemize}
\end{block}
\end{frame}

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

\begin{frame}{\color{gate-dark-green} Exercise 2: Develop/Test Cycle }
\begin{block}{Apply Best Practice}
Change the implementation from {\em Exercise 1} to:
\begin{itemize}
  \item use a parameter for the input annotation set;
  \item use a parameter for the {\tt Token} annotation type;
  \item make sure these parameters have good defaults, and documentation;
\end{itemize}
\end{block}
\begin{block}{Test it!}
\begin{itemize}
  \item Start GATE Developer, load a document, create an instance of the
  Unicode Tokeniser;
  \item load the {\tt module7} CREOLE plugin, create an instance of your
  PR; create a Corpus Pipeline and add the two PRs to it;
  \item run the pipeline over the document and check it works.
\end{itemize}
\end{block}
\end{frame}

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

\begin{frame}{Best Practice: CREOLE Metadata as Java Annotations}
Starting with GATE 5, the CREOLE metadata can also be added as Java 5
annotations directly in the source code. This is now the recommended way of
creating CREOLE configuration because:
\begin{itemize}
  \item it is easier to maintain;
  \item it makes it impossible to have a version mismatch between the
  implementation and its configuration data;
  \item takes advantage of IDE support (e.g. Eclipse).
  \item uses inheritance: parameters inherited from super classes and
  interfaces (e.g.  {\tt document} and {\tt corpus} on LanguageAnalyser) need
  not be declared again.
\end{itemize}
\end{frame}

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

\begin{frame}[fragile]{CREOLE Annotations: @CreoleResource}
Used for Resource implementations. Main attributes:
\begin{description}
  \item [name] (String) the name of the resource.
  \item [comment] (String) a descriptive comment about the resource 
  \item [helpURL] (String) a URL to a help document on the web for this resource.
  \item [icon] (String) the icon to use to represent the resource in GATE Developer. 
\end{description}
\begin{block}{Example}
\begin{lstlisting}[basicstyle=\scriptsize\ttfamily]
@CreoleResource (name = "Document Stats", 
                 comment = "Calculates document statistics.")
public class DocStats extends AbstractLanguageAnalyser {
...
}
\end{lstlisting}
\end{block}
\end{frame}

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

\begin{frame}{CREOLE Annotations: @CreoleResource}
\begin{block}{Attributes for Visual Resources}
If the resource being configred is a Visual Resource, you can also use the
following attributes: 
\begin{description}
  \item [guiType] (GuiType enum) the type of GUI this resource defines. XML
  equivalent <GUI TYPE="LARGE|SMALL">.
  \item [resourceDisplayed] (String) the class name of the resource type that
  this VR displays, e.g. "gate.Corpus".
  \item [mainViewer] (boolean) is this VR the {\em most important} viewer for
  its displayed resource type?
\end{description}
\end{block}
\end{frame}

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

\begin{frame}[fragile]{CREOLE Annotations: @CreoleParameter}
Creole parameters are identified by {\tt @CreoleParameter} annotations on their
setter method. Main attributes include:
\begin{description}
  \item [comment] (String) an optional descriptive comment about the parameter.
  \item [defaultValue] (String) the optional default value for this parameter.
  \item [suffixes] (String) for URL-valued parameters, a semicolon-separated
  list of default file suffixes that this parameter accepts.
\end{description}
\begin{block}{Example}
\begin{lstlisting}[basicstyle=\scriptsize\ttfamily]

  @CreoleParameter(defaultValue="",
          comment="The name for the input annotation set.")
  public void setInputASName(String inputAsName) {
    this.inputAsName = inputAsName;
  }
\end{lstlisting}

\end{block}
\end{frame}

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

\begin{frame}[fragile]{CREOLE Annotations: Parameter Types}
You can also use the following annotations to mark the type of a CREOLE
parameter:
\begin{description}
\item[@Optional] for parameters that are not required.
\item[@RunTime] for run-time parameters. 
\end{description}
\begin{block}{Corrected Example}
\begin{lstlisting}[basicstyle=\scriptsize\ttfamily]
  @Optional
  @RunTime
  @CreoleParameter(defaultValue="", 
      comment="The name for the input annotation set.")
  public void setInputASName(String inputAsName) {
    this.inputAsName = inputAsName;
  }
\end{lstlisting}
\end{block}
{\color{gate-light-green} TIP: }More info at
\href{http://gate.ac.uk/userguide/sec:creole-model:config}{http://gate.ac.uk/userguide/sec:creole-model:config}
\end{frame}

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

\begin{frame}[fragile]{Putting it All Together}
\begin{itemize}
  \item You still need a {\tt creole.xml} file to define a CREOLE plugin!
  \item Your {\tt <RESOURCE>} entries only need the {\tt <CLASS>} element.
\end{itemize}
\begin{block}{Example:}
\begin{lstlisting}[language=XML, basicstyle=\scriptsize\ttfamily]
<CREOLE-DIRECTORY><CREOLE>
  <RESOURCE> 
    <CLASS>module7.DocStats</CLASS>
  </RESOURCE>
</CREOLE></CREOLE-DIRECTORY>
\end{lstlisting}
\end{block}
\begin{itemize}
  \item {\bf OR}, if you have a {\tt <JAR>} element, you can ask GATE to scan
  it for classes annotated with {\tt @CreoleResource}.
\end{itemize}
\begin{block}{Example:}
\begin{lstlisting}[language=XML, basicstyle=\scriptsize\ttfamily]
<CREOLE-DIRECTORY><CREOLE>
<JAR SCAN="true">module7.jar</JAR>
</CREOLE></CREOLE-DIRECTORY>
\end{lstlisting}
\end{block}
\end{frame}

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

\begin{frame}{\color{gate-dark-green} Exercise 3: Switch to CREOLE Annotations}
Change the implementation from {\em Exercise 2} to:
\begin{itemize}
  \item use CREOLE annotations for the resource;
  \item use CREOLE annotations for the parameters;
  \item use the jar scanning technique for the creole.xml file.
\end{itemize}

\begin{block}{Test it!}
Repeat the test procedure from {\em Exercise 2} and check it still works as
expected.
\end{block}
\end{frame}

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

\begin{frame}[fragile]{\color{gate-dark-green} Exercise 4: Better Statistics}
Change the implementation from {\em Exercise 3} to also calculate counts for
all {\bf words}, all {\bf nouns}, all {\bf verbs}.

{\color{gate-light-green} TIPs:}\\
You will need to run a Sentence Splitter, and POS Tagger after the Tokeniser,
in order to get the part-of-speech information.

Definitions:
\begin{description}
  \item[word] \verb!{Token.kind=="word"}!
  \item[noun] \verb!{Token.category.startsWith("NN")}!
  \item[verb] \verb!{Token.category.startsWith("VB")}!
\end{description}

\begin{block}{Test it!}
\end{block}
\end{frame}

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

\subsection{Your First Visual Resource}

\begin{frame}[fragile]{Visual Resources}
\begin{itemize}
  \item  Visual Resources provide UI elements (Swing components) for building
  user interfaces.
  \item They are classes that implement the \lstinline!gate.VisualResource!
  interface.
  \item They are associated with a type of resource via CREOLE metadata (which
  is used as a model for the view represented by the VR).
  \item The abstract class \lstinline!gate.creole.AbstractVisualResource! can
  be used a starting point.
\end{itemize}
\end{frame}

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

\begin{frame}[fragile]{Visual Resource API}
\begin{block}{Visual Resource API}
Visual resources extend the \lstinline!gate.Resource! interface, with :
\begin{lstlisting}[texcl]
/** set the object to be displayed */
public void setTarget(Object target);
\end{lstlisting}
\end{block}
\begin{block}{AbstractVisualResource}
\begin{itemize}
  \item extends \lstinline!javax.swing.JPanel!;
  \item implements all the methods required by \lstinline!gate.Resource!;
  \item extending classes only need to implement:
  \begin{itemize}
    \item \lstinline!public Resource init()!: initialise the resource (i.e.
    build the required UI elements);
    \item \lstinline!public void setTarget(Object target)!: sets the model for
    this view.
  \end{itemize}
\end{itemize}
\end{block}
\end{frame}

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

\begin{frame}[fragile]{Visual Resource CREOLE Metadata}
\begin{itemize}
  \item A Visual Resource is associated with a given type of object that it can
  display (or edit, configure). This association is done via CREOLE metadata on
  the VR implementation.
  \item From the API, the VR is populated by calling
  \lstinline!setTarget(Object target)!.
  \item In GATE Developer, the appropriate VR types are instantiated
  automatically when new resorces are created. E.g., when a new Document is
  created, all VR registered as capable of displaying \lstinline!gate.Document!
  targets are instantiated.
\end{itemize}
\end{frame}

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

\begin{frame}[fragile]{VR Metadata Example}
\begin{block}{CREOLE Annotations:}
\begin{lstlisting}
@CreoleResource(name="Statistics Viewer", 
        comment="Shows document statistics",
        resourceDisplayed="gate.Document",
        guiType=GuiType.LARGE,
        mainViewer=true)
public class StatsViewer extends AbstractVisualResource
\end{lstlisting}
\end{block}
\begin{block}{XML:}
\begin{lstlisting}[language=XML, basicstyle=\scriptsize\ttfamily]
<RESOURCE>
  <NAME>Statistics Viewer</NAME>
  <CLASS>module7.StatsViewer</CLASS>
  <COMMENT>Shows document statistics</COMMENT>
  <GUI TYPE="large"><MAIN_VIEWER />
    <RESOURCE_DISPLAYED>gate.Document</RESOURCE_DISPLAYED>
  </GUI>
</RESOURCE>
\end{lstlisting}
\end{block}
\end{frame}

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

\begin{frame}[fragile]{\color{gate-dark-green} Exercise 5: Show the Statistics}
\begin{itemize}
  \item Create a VR that, given a document, can show the statistics produced by
  the DocStats language analyser.
  \item add CREOLE metadata to associate the new VR with the interface
  \lstinline!gate.Document!;
\end{itemize}
You can use a simple \lstinline!JTextPane! to show a \lstinline!.toString()!
value for the document's features.
\end{frame}

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

\begin{frame}[fragile]{\color{gate-dark-green} Exercise 5: Solution}
\omitfromhandout<1>
{\color{gate-light-red} Try not to use this!}
\pause
\begin{lstlisting}[basicstyle=\tiny\ttfamily]
package module7;
import javax.swing.*;
import gate.*;
import gate.creole.*;
import gate.event.FeatureMapListener;
public class StatsViewer extends AbstractVisualResource 
    implements FeatureMapListener{
  private JTextPane textPane;
  private FeatureMap targetFeatures;
  public Resource init() throws ResourceInstantiationException {
    textPane = new JTextPane();
    add(new JScrollPane(textPane));
    return this;
  }
  public void setTarget(Object target) {
    if(targetFeatures != null) targetFeatures.removeFeatureMapListener(this);
    targetFeatures = ((Document)target).getFeatures();
    targetFeatures.addFeatureMapListener(this);
    featureMapUpdated();
  }
  public void featureMapUpdated() {
    textPane.setText(targetFeatures.toString()); 
  } 
}
\end{lstlisting}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Advanced CREOLE}
\subsection{CREOLE Management}

\begin{frame}{The CREOLE and DataStore Registers}
\begin{block}{The CREOLE Register}
\begin{itemize}
  \item Stores all CREOLE data, including:
  \begin{itemize}
    \item which plugins are loaded;
    \item which types of CREOLE Resources have been defined;
    \item loaded instances of each resource type;
    \item which Visual Resources can display any resource type;
  \end{itemize}
  \item fires events when resources are loaded and deleted;
  \item forwards all events from the DataStore Register (see below).
\end{itemize}
\end{block}
\begin{block}{The DataStore Register}
\begin{itemize}
  \item is a \lstinline!java.util.Set! of DataStore objects.
  \item fires events when datastores are created, opened and closed. 
\end{itemize}
\end{block}
\end{frame}

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

\begin{frame}[fragile]{CREOLE Register and its Events}
\begin{lstlisting}[texcl]
//Obtain a pointer to the CREOLE Register
CreoleRegister cReg = Gate.getCreoleRegister();
//listen to CREOLE events
cReg.addCreoleListener(new CreoleListener() {
  public void resourceUnloaded(CreoleEvent e) { ... }
  public void resourceRenamed(Resource resource, 
      String oldName, String newName) { ... }
  public void resourceLoaded(CreoleEvent e) { ... }
  public void datastoreOpened(CreoleEvent e) { ... }
  public void datastoreCreated(CreoleEvent e) { ... }
  public void datastoreClosed(CreoleEvent e) { ... }
});
//remove a registered listener
cReg.removeCreoleListener(aListener);
\end{lstlisting}
\end{frame}

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

\begin{frame}[fragile]{Other CREOLE APIs}
\begin{block}{Plugins Management}
\begin{lstlisting}[texcl]
//load a new CREOLE plugin
try {
  cReg.registerDirectories(new URL("..."));
  // register a single resource class without using creole.xml
  cReg.registerComponent(MyResource.class);
} catch(GateException e1) { ... }
//get all loaded plugins
cReg.getDirectories();
//remove a loaded plugin
cReg.removeDirectory( ... );
\end{lstlisting}
\end{block}
\end{frame}

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

\begin{frame}[fragile]{Other CREOLE APIs (continued)}
\begin{block}{Find Loaded Resources}
\begin{lstlisting}[texcl]
//find all resources of a given type
try {
  cReg.getAllInstances("gate.LanguageAnalyser");
} catch(GateException e1) { ... }
\end{lstlisting}
\end{block}

\begin{block}{Resource Types}
\begin{lstlisting}[texcl]
cReg.getPrTypes();  //get PR types (class  names)
cReg.getLrTypes();  //get LR types (class  names)
cReg.getVrTypes();  //get VR types (class  names)
\end{lstlisting}
\end{block}
\end{frame}

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

\begin{frame}[fragile]{Other CREOLE APIs (continued)}
\begin{block}{CREOLE Metadata}
\begin{lstlisting}[texcl]
//Obtain the Resource Data about a resource
ResourceData rData = cReg.get("resource.class.name");
//get the list of instances 
List<Resource> instances = rData.getInstantiations();
//get the list of parameters
ParameterList pList = rData.getParameterList();
//get the Init-time / Run-time parameters
List<List<Parameter>> someParams;
someParams = pList.getRuntimeParameters();
someParams = pList.getInitimeParameters();
\end{lstlisting}
\end{block}
\end{frame}

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

\begin{frame}[fragile]{\color{gate-dark-green} Exercise 6: CREOLE Metadata}
\begin{itemize}
  \item load the ANNIE application;
  \item find out which plugins are loaded;
  \item find out which PR \textbf{instances} exist;
  \item find out which PR types are known to the system;
	\item find out what parameters they have.
\end{itemize}

\begin{block}{You may find this useful:}
\begin{lstlisting}[texcl]
public void main(String[] args) throws Exception{
  Gate.init();
  //load the ANNIE application
  File annieGappFile = new File(
      new File(Gate.getPluginsHome(), "ANNIE"), 
      "ANNIE_with_defaults.gapp"); 
  PersistenceManager.loadObjectFromFile(annieGappFile);
  // ...
}
\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{http://gate.ac.uk} (Our website)
  \item \url{http://gate.ac.uk/mail/} (Our mailing list)
\end{itemize}
\end{block}
\end{frame}

\end{document}
