# Arrow UDF Java Server
This article provides a step-by-step guide for installing the RisingWave Java UDF SDK, defining functions using Java, starting a Java process as a UDF server, and declaring and using UDFs in RisingWave.
## Prerequisites
- Ensure that you have [Java Developer's Kit (JDK)](https://www.oracle.com/technetwork/java/javase/downloads/index.html) (11 or later) installed on your computer.
- Ensure that you have [Apache Maven](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html) (3.0 or later) installed on your computer. Maven is a build tool that helps manage Java projects and dependencies.
## 1. Create a Maven project from template
The RisingWave Java UDF SDK is distributed as a Maven artifact. We have prepared a sample project so you don't have to create it from scratch. Run the following command to clone the template repository.
```sh
git clone https://github.com/risingwavelabs/risingwave-java-udf-template.git
```
<details>
<summary>I'd like to start from scratch</summary>
To create a new project using the RisingWave Java UDF SDK, follow these steps:
Generate a new Maven project:
```sh
mvn archetype:generate -DgroupId=com.example -DartifactId=udf-example -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
```
Configure your `pom.xml` file as follows:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>udf-example</artifactId>
<version>1.0-SNAPSHOT</version>
<dependencies>
<dependency>
<groupId>com.risingwave</groupId>
<artifactId>risingwave-udf</artifactId>
<version>0.2.0</version>
</dependency>
</dependencies>
</project>
```
The `--add-opens` flag must be added when running unit tests through Maven:
```xml
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.2.5</version>
<configuration>
<argLine>--add-opens=java.base/java.nio=ALL-UNNAMED</argLine>
</configuration>
</plugin>
</plugins>
</build>
```
</details>
## 2. Define your functions in Java
### Scalar functions
A user-defined scalar function maps zero, one, or multiple scalar values to a new scalar value.
In order to define a scalar function, you have to create a new class that implements the `ScalarFunction`
interface in `com.risingwave.functions` and implement exactly one evaluation method named `eval(...)`.
This method must be declared public and non-static.
Any data type listed in [Data type mapping](udf-java.md#data-type-mapping) can be used as a parameter or return type of an evaluation method.
Here's an example of a scalar function that calculates the greatest common divisor (GCD) of two integers:
```java
import com.risingwave.functions.ScalarFunction;
public class Gcd implements ScalarFunction {
public int eval(int a, int b) {
while (b != 0) {
int temp = b;
b = a % b;
a = temp;
}
return a;
}
}
```
:::note Differences with Flink
- The `ScalarFunction` is an interface instead of an abstract class.
- Multiple overloaded `eval` methods are not supported.
- Variable arguments such as `eval(Integer...)` are not supported.
:::
### Table functions
A user-defined table function maps zero, one, or multiple scalar values to one or multiple
rows (structured types).
In order to define a table function, you have to create a new class that implements the `TableFunction`
interface in `com.risingwave.functions` and implement exactly one evaluation method named `eval(...)`.
This method must be declared public and non-static.
The return type must be an `Iterator` of any data type listed in [Data type mapping](udf-java.md#data-type-mapping).
Similar to scalar functions, input and output data types are automatically extracted using reflection.
This includes the generic argument T of the return value for determining an output data type.
Here's an example of a table function that generates a series of integers:
```java
import com.risingwave.functions.TableFunction;
public class Series implements TableFunction {
public Iterator<Integer> eval(int n) {
return java.util.stream.IntStream.range(0, n).iterator();
}
}
```
:::note Differences with Flink
- The `TableFunction` is an interface instead of an abstract class. It has no generic arguments.
- Instead of calling `collect` to emit a row, the `eval` method returns an `Iterator` of the output rows.
- Multiple overloaded `eval` methods are not supported.
- Variable arguments such as `eval(Integer...)` are not supported.
:::
## 3. Start a UDF server
Run the following command to create a UDF server and register for the functions you defined.
```java
import com.risingwave.functions.UdfServer;
public class App {
public static void main(String[] args) {
try (var server = new UdfServer("0.0.0.0", 8815)) {
// Register functions
server.addFunction("gcd", new Gcd());
server.addFunction("series", new Series());
// Start the server
server.start();
server.awaitTermination();
} catch (Exception e) {
e.printStackTrace();
}
}
}
```
Run the following command to start the UDF server.
```sh
_JAVA_OPTIONS="--add-opens=java.base/java.nio=ALL-UNNAMED" mvn exec:java -Dexec.mainClass="com.example.App"
```
The UDF server will start running, allowing you to call the defined UDFs from `arrow-udf-flight`.
## Data type mapping
The following table shows the type mapping between Arrow and Java:
| Arrow Type | Java Type |
| ----------------- | ------------------------- |
| Null | Void |
| Boolean | boolean, Boolean |
| Int8 | byte, Byte |
| Int16 | short, Short |
| Int32 | int, Integer |
| Int64 | long, Long |
| UInt8 | byte, Byte |
| UInt16 | char, Character |
| UInt32 | int, Integer |
| UInt64 | long, Long |
| Float32 | float, Float |
| Float64 | double, Double |
| Date32 | java.time.LocalDate |
| Time64 | java.time.LocalTime |
| Timestamp | java.time.LocalDateTime |
| String | String |
| LargeString | String |
| Binary | byte[] |
| LargeBinary | byte[] |
| List<T> | T'[] |
| Struct | user-defined class. see [example](#example---struct-type). |
| Extension Type | Metadata | Java Type |
| ----------------- | ------------------- | ------------------------- |
| Decimal | `arrowudf.decimal` | java.math.BigDecimal |
| Json | `arrowudf.json` | String (use `@DataTypeHint("JSON") String` as the type. See [example](#example---jsonb)) |
### Example - JSONB
```java title="Define the function in Java"
import com.google.gson.Gson;
// Returns the i-th element of a JSON array.
public class JsonAccess implements ScalarFunction {
static Gson gson = new Gson();
public @DataTypeHint("JSON") String eval(@DataTypeHint("JSON") String json, int index) {
if (json == null)
return null;
var array = gson.fromJson(json, Object[].class);
if (index >= array.length || index < 0)
return null;
var obj = array[index];
return gson.toJson(obj);
}
}
```
### Example - Struct type
```java title="Define the function in Java"
// Split a socket address into host and port.
public static class IpPort implements ScalarFunction {
public static class SocketAddr {
public String host;
public short port;
}
public SocketAddr eval(String addr) {
var socketAddr = new SocketAddr();
var parts = addr.split(":");
socketAddr.host = parts[0];
socketAddr.port = Short.parseShort(parts[1]);
return socketAddr;
}
}
```