---
title: "R6 Generator Maven Plugin: Getting started"
author: "Rob Challen"
output: 
  html_document
vignette: >
  %\VignetteIndexEntry{R6 Generator Maven Plugin: Getting started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(tidyverse)
here::i_am("vignettes/testRapi.Rmd")
source(here::here("vignettes/codeSnip.R"))
```

Maven plugin and annotation processor to write glue code to allow correctly annotated java class to be used within R as an set of R6 classes.

## Rationale

R can use RJava or jsr223 to communicate with java. R has a class system called R6.

If you want to use a java library in R there is potentially a lot of glue code needed, and R library specific packaging configuration required.

However if you don't mind writing an R-centric API in Java you can generate all of this glue code using a few java annotations and the normal javadoc annotations. This plugin aims to provide an annotation processor that writes that glue code and creates a fairly transparent connection between java code and R code, with a minimum of hard work. The focus of this is streamlining the creation of R libraries by Java developers, rather than allowing access to arbitrary Java code from R.

The ultimate aim of this plugin to allow java developers to provide simple APIs for their libraries, package their library using maven, push it to github and for that to become seamlessly available as an R library, with a minimal amount of fuss.

## Basic usage

### Write a java api:

```{r results='asis', echo=FALSE}
codeSnip("java",
         filename=here::here("java/src/main/java/uk/co/terminological/rjava/test/MinimalExample.java"),"START","END") #,35,51)
```

Key points:

* You can annotate multiple classes with @RClass.
* Only public methods annotated with @RMethod will feature in the R library
* you cannot overload methods or constructors. Only one method with a given name is supported, and only one annotated constructor.
* static and non static java methods are supported.
* Objects that can be translated into R are returned by value
* Other objects are passed around in R by reference as R6 Objects mirroring the layout of the java code.
* Such objects can interact with each other in the same java api engine (see below)

### Package it:

Required Maven runtime dependency

```{r results='asis', echo=FALSE}
codeSnip("xml",
         filename=here::here("java/pom.xml"),"DEPS_START","DEPS_END") #,35,51)
```

Repository configuration if you want to use the unstable `main-SNAPSHOT` version of the `r6-generator`.

```{r results='asis', echo=FALSE}
codeSnip("xml",
         filename=here::here("java/pom.xml"),"REPOSITORIES_START","REPOSITORIES_END") #,35,51)
```

Maven plugin example configuration:

```{r results='asis', echo=FALSE}
codeSnip("xml",
         filename=here::here("java/pom.xml"),"BUILD_START","BUILD_END") #,35,51)
```

And with this in place, a call to mvn package or mvn install will create your R library by adding files to your java source tree in the directory.
Push your java source tree to github (Optional). 

### Run it from R:


```{r}

# library(devtools)

# if you are using locally:
# devtools::install_local("~/Git/your-project-id")
# devtools::load_all("~/Git/your-project-id")
# OR if you pushed the project to github
# install_github("your-github-name/your-project-id")

# a basic smoke test

# the JavaApi class is the entry point for R to your Java code.
J <- testRapi::JavaApi$get()

# all the API classes and methods are classes attached to the J java api object
eg = J$MinimalExample$new()
df = eg$demo(dataframe = diamonds, message = "The diamonds dataframe")
nrow(df)
```

For basic info about the plugin see: 
https://github.com/terminological/r6-generator

For a more complete working example and further documentation see: 
https://github.com/terminological/r6-generator-docs