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 Run and Cloud Run for Anthos
- Knative-based environments
The Functions Framework for Java uses
Java and
Maven (the mvn
command),
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
gcloud
command-line.
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.xml
file of your project:
<dependency>
<groupId>com.google.cloud.functions</groupId>
<artifactId>functions-framework-api</artifactId>
<version>1.0.4</version>
<scope>provided</scope>
</dependency>
If you are using Gradle to build your functions, you can define the Functions
Framework dependency in your build.gradle
project file as follows:
dependencies {
implementation 'com.google.cloud.functions:functions-framework-api:1.0.4'
}
Create a file src/main/java/com/example/HelloWorld.java
with the following
contents:
package com.example;
import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
public class HelloWorld implements HttpFunction {
@Override
public void service(HttpRequest request, HttpResponse response)
throws Exception {
response.getWriter().write("Hello, World\n");
}
}
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).
Create a file src/main/java/com/example/Background.java
with the following
contents:
package com.example;
import com.google.cloud.functions.Context;
import com.google.cloud.functions.RawBackgroundFunction;
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import java.util.logging.Logger;
public class Background implements RawBackgroundFunction {
private static final Logger logger =
Logger.getLogger(Background.class.getName());
@Override
public void accept(String json, Context context) {
Gson gson = new Gson();
JsonObject jsonObject = gson.fromJson(json, JsonObject.class);
logger.info("Received JSON object: " + jsonObject);
}
}
Create a file src/main/java/com/example/PubSubBackground
with the following
contents:
package com.example;
import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import java.util.Map;
import java.util.logging.Logger;
// This is the Pub/Sub message format from the Pub/Sub emulator.
class PubSubMessage {
String data;
Map<String, String> attributes;
String messageId;
String publishTime;
}
public class PubSubBackground implements BackgroundFunction<PubSubMessage> {
private static final Logger logger =
Logger.getLogger(PubSubBackground.class.getName());
@Override
public void accept(PubSubMessage pubSubMessage, Context context) {
logger.info("Received message with id " + context.eventId());
}
}
The Maven plugin called function-maven-plugin
allows you to run functions
on your development machine.
You can configure the plugin in pom.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
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
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.1.1' \
-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.1.1 \
--classpath myfunction.jar \
--target com.example.HelloWorld
From Gradle, similarily to running functions with the Functions Framework jar,
we can invoke the Invoker
class with a JavaExec
task.
configurations {
invoker
}
dependencies {
implementation 'com.google.cloud.functions:functions-framework-api:1.0.4'
invoker 'com.google.cloud.functions.invoker:java-function-invoker:1.1.1'
}
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
There are a number of options that can be used to configure the Functions Framework, whether run directly or on the command line.
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
- Maven
pom.xml
:<functionTarget>com.example.HelloWorld</functionTarget>
- Maven CLI argument:
-Drun.functionTarget=com.example.HelloWorld
- Gradle CLI argument:
-Prun.functionTarget=com.example.HelloWorld
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
- Maven
pom.xml
:<port>12345</port>
- Maven CLI argument:
-Drun.port=12345
- Gradle CLI argument:
-Prun.port=12345
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 in pom.xml
. When invoking the Functions
Framework directly, you must use --classpath
to indicate how to find the code
and its dependencies. For example:
java -jar java-function-invoker-1.1.1 \
--classpath 'myfunction.jar:/some/directory:/some/library/*' \
--target com.example.HelloWorld
The --classpath
option works like
java -classpath
.
It is a list of entries separated by :
(;
on Windows), where each entry is:
- a directory, in which case class
com.example.Foo
is looked for in a filecom/example/Foo.class
under that directory; - a jar file, in which case class
com.example.Foo
is looked for in a filecom/example/Foo.class
in 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.
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.