Functions Framework for Java

An open source FaaS (Function as a service) framework for writing portable Java functions -- brought to you by the Google Cloud Functions team.

The Functions Framework lets you write lightweight functions that run in many different environments, including:

• Google Cloud Functions
• Your local development machine
• Cloud RunandCloud Run for Anthos
• Knative-based environments

Installation

The Functions Framework for Java uses Javaand Maven(themvncommand), for building and deploying functions from source.

However, it is also possible to build your functions using Gradle,as JAR archives, that you will deploy with the gcloudcommand-line.

Quickstart: Hello, World on your local machine

A function is typically structured as a Maven project. We recommend using an IDE that supports Maven to create the Maven project. Add this dependency in the pom.xmlfile of your project:

<dependency>
<groupId>com.google.cloud.functions</groupId>
<artifactId>functions-framework-api</artifactId>
<version>1.1.2</version>
<scope>provided</scope>
</dependency>

If you are using Gradle to build your functions, you can define the Functions Framework dependency in yourbuild.gradleproject file as follows:

dependencies {
implementation'com.google.cloud.functions:functions-framework-api:1.1.2'
}

Writing an HTTP function

Create a filesrc/main/java/com/example/HelloWorld.javawith the following contents:

packagecom.example;

importcom.google.cloud.functions.HttpFunction;
importcom.google.cloud.functions.HttpRequest;
importcom.google.cloud.functions.HttpResponse;

publicclassHelloWorldimplementsHttpFunction{
@Override
publicvoidservice(HttpRequestrequest,HttpResponseresponse)
throwsException{
response.getWriter().write("Hello, World\n");
}
}

Quickstart: Create a Background Function

There are two ways to write a Background function, which differ in how the payload of the incoming event is represented. In a "raw" background function this payload is presented as a JSON-encoded Java string. In a "typed" background function the Functions Framework deserializes the JSON payload into a Plain Old Java Object (POJO).

Writing a Raw Background Function

Create a filesrc/main/java/com/example/Background.javawith the following contents:

packagecom.example;

importcom.google.cloud.functions.Context;
importcom.google.cloud.functions.RawBackgroundFunction;
importcom.google.gson.Gson;
importcom.google.gson.JsonObject;
importjava.util.logging.Logger;

publicclassBackgroundimplementsRawBackgroundFunction{
privatestaticfinalLoggerlogger=
Logger.getLogger(Background.class.getName());

@Override
publicvoidaccept(Stringjson,Contextcontext) {
Gsongson=newGson();
JsonObjectjsonObject=gson.fromJson(json,JsonObject.class);
logger.info("Received JSON object:"+jsonObject);
}
}

Writing a Typed Background Function

Create a filesrc/main/java/com/example/PubSubBackgroundwith the following contents:

packagecom.example;

importcom.google.cloud.functions.BackgroundFunction;
importcom.google.cloud.functions.Context;
importjava.util.Map;
importjava.util.logging.Logger;

// This is the Pub/Sub message format from the Pub/Sub emulator.
classPubSubMessage{
Stringdata;
Map<String,String>attributes;
StringmessageId;
StringpublishTime;
}

publicclassPubSubBackgroundimplementsBackgroundFunction<PubSubMessage> {
privatestaticfinalLoggerlogger=
Logger.getLogger(PubSubBackground.class.getName());

@Override
publicvoidaccept(PubSubMessagepubSubMessage,Contextcontext) {
logger.info("Received message with id"+context.eventId());
}
}

Running a function with the Maven plugin

The Maven plugin calledfunction-maven-pluginallows you to run functions on your development machine.

Configuration inpom.xml

You can configure the plugin inpom.xml:

<plugin>
<groupId>com.google.cloud.functions</groupId>
<artifactId>function-maven-plugin</artifactId>
<version>0.10.1</version>
<configuration>
<functionTarget>com.example.HelloWorld</functionTarget>
</configuration>
</plugin>

Then run it from the command line:

mvn function:run

Configuration on the command line

You can alternatively configure the plugin with properties on the command line:

mvn com.google.cloud.functions:function-maven-plugin:0.10.1:run \
-Drun.functionTarget=com.example.HelloWorld

Running the Functions Framework directly

You can also run a function by using the Functions Framework jar directly. Copy the Functions Framework jar to a local location like this:

mvn dependency:copy \
-Dartifact='com.google.cloud.functions.invoker:java-function-invoker:1.3.2'\
-DoutputDirectory=.

In this example we use the current directory.but you can specify any other directory to copy to. Then run your function:

java -jar java-function-invoker-1.3.2 \
--classpath myfunction.jar \
--target com.example.HelloWorld

Running a function with Gradle

From Gradle, similarily to running functions with the Functions Framework jar, we can invoke theInvokerclass with aJavaExectask.

Configuration inbuild.gradle

configurations {
invoker
}

dependencies {
implementation'com.google.cloud.functions:functions-framework-api:1.1.2'
invoker'com.google.cloud.functions.invoker:java-function-invoker:1.3.2'
}

tasks.register("runFunction",JavaExec) {
main='com.google.cloud.functions.invoker.runner.Invoker'
classpath(configurations.invoker)
inputs.files(configurations.runtimeClasspath, sourceSets.main.output)
args(
'--target',project.findProperty('run.functionTarget'),
'--port',project.findProperty('run.port')?:8080
)
doFirst {
args('--classpath',files(configurations.runtimeClasspath, sourceSets.main.output).asPath)
}
}

Then in your terminal or IDE, you will be able to run the function locally with:

gradle runFunction -Prun.functionTarget=com.example.HelloWorld \
-Prun.port=8080

Or if you use the Gradle wrapper provided by your Gradle project build:

./gradlew runFunction -Prun.functionTarget=com.example.HelloWorld \
-Prun.port=8080

Functions Framework configuration

There are a number of options that can be used to configure the Functions Framework, whether run directly or on the command line.

Which function to run

A function is a Java class. You must specify the name of that class when running the Functions Framework:

--target com.example.HelloWorld
<functionTarget>com.example.HelloWorld</functionTarget>
-Drun.functionTarget=com.example.HelloWorld
-Prun.functionTarget=com.example.HelloWorld

• Invoker argument:--target com.example.HelloWorld
• Mavenpom.xml:<functionTarget>com.example.HelloWorld</functionTarget>
• Maven CLI argument:-Drun.functionTarget=com.example.HelloWorld
• Gradle CLI argument:-Prun.functionTarget=com.example.HelloWorld

Which port to listen on

The Functions Framework is an HTTP server that directs incoming HTTP requests to the function code. By default this server listens on port 8080. Specify an alternative value like this:

• Invoker argument:--port 12345
• Mavenpom.xml:<port>12345</port>
• Maven CLI argument:-Drun.port=12345
• Gradle CLI argument:-Prun.port=12345

Function classpath

Function code runs with a classpath that includes the function code itself and its dependencies. The Maven plugin automatically computes the classpath based on the dependencies expressed inpom.xml.When invoking the Functions Framework directly, you must use--classpathto indicate how to find the code and its dependencies. For example:

java -jar java-function-invoker-1.3.2 \
--classpath 'myfunction.jar:/some/directory:/some/library/*' \
--target com.example.HelloWorld

The--classpathoption works like java -classpath. It is a list of entries separated by:(;on Windows), where each entry is:

• a directory, in which case classcom.example.Foois looked for in a file com/example/Foo.classunder that directory;
• a jar file, in which case classcom.example.Foois looked for in a file com/example/Foo.classin that jar file;
• a directory followed by/*(\*on Windows), in which case each jar file in that directory (file calledfoo.jar) is treated the same way as if it had been named explicitly.

Simplifying the classpath

Specifying the right classpath can be tricky. A simpler alternative is to build the function as a "fat jar", where the function code and all its dependencies are in a single jar file. Then--classpath myfatfunction.jar is enough. An example of how this is done is the Functions Framework jar itself, as seen here.

Alternatively, you can arrange for your jar to have its own classpath, as described here.