* Rename package names to com.microsoft.azure.functions and com.microsoft.azure.functions.annotation
This commit is contained in:
Pragna Gopa 2018-05-17 14:18:52 -07:00 коммит произвёл GitHub
Родитель cecc79f24b
Коммит e394ed30ca
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
39 изменённых файлов: 316 добавлений и 126 удалений

2
.gitignore поставляемый
Просмотреть файл

@ -21,3 +21,5 @@
# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
hs_err_pid*
/.idea/*
/target/*

251
README.md
Просмотреть файл

@ -1,14 +1,245 @@
# Azure Functions Java Library
# Contributing
This package contains libraries to author Azure Functions in Java.
This project welcomes contributions and suggestions. Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.microsoft.com.
### Usage
Use this package by including the following snippet in your `pom.xml`.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
provided by the bot. You will only need to do this once across all repos using our CLA.
```xml
<dependency>
<groupId>com.microsoft.azure.functions</groupId>
<artifactId>azure-functions-java-library</artifactId>
<version>1.0.0-beta-1</version>
</dependency>
```
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
### Annotation for Triggers and Bindings
Instead of writing `function.json`, you can use annotations in code to specify triggers and bindings of your functions.
`function.json` can be automatically generated by [Maven Plugin for Azure Functions](https://github.com/Microsoft/azure-maven-plugins/tree/master/azure-functions-maven-plugin).
The following table lists the Java annotations for each binding type.
Binding | Annotation
---|---
HTTP | <ul><li>`HttpTrigger`</li><li>`HttpOutput`</li></ul>
Storage Blob | <ul><li>`BlobTrigger`</li><li>`BlobInput`</li><li>`BlobOutput`</li></ul>
Storage Queue | <ul><li>`QueueTrigger`</li><li>`QueueOutput`</li></ul>
Storage Table | <ul><li>`TableInput`</li><li>`TableOutput`</li></ul>
Timer | <ul><li>`TimerTrigger`</li></ul>
# Building Microsoft Azure Functions in Java
## Prerequisites
* JDK 8
* Maven
* JAVA_HOME environment variable
* Node
* NPM Azure Functions CLI
## Programming Model
Your Azure function should be a stateless method to process input and produce output. Although you are allowed to write instance methods, your function must not depend on any instance fields of the class. You need to make sure all the function methods are `public` accessible.
Typically an Azure function is invoked because of one trigger. Your function needs to process that trigger (sometimes with additional inputs) and gives one or more output values.
All the input and output bindings can be defined in `function.json` (not recommended), or in the Java method by using annotations (recommended). All the types and annotations used in this document are included in the `azure-functions-java-library` package.
Here is an example for a simple Azure function written in Java:
```Java
package com.example;
import com.microsoft.azure.functions.annotation.*;
public class MyClass {
@FunctionName("echo")
public static String echo(@HttpTrigger(name = "req", methods = { "post" }, authLevel = AuthorizationLevel.ANONYMOUS) String in) {
return "Hello, " + in + ".";
}
}
```
### Including 3rd Party Libraries
Azure Functions only accept one single JAR file. Therefore you are required to package all your dependencies into one single JAR. A simple approach is to add the following plugin into your `pom.xml`:
```xml
<plugin>
<artifactId>maven-shade-plugin</artifactId>
<version>3.1.0</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<filters>
<filter>
<artifact>*:*</artifact>
<excludes>
<exclude>META-INF/*.SF</exclude>
<exclude>META-INF/*.DSA</exclude>
<exclude>META-INF/*.RSA</exclude>
</excludes>
</filter>
</filters>
</configuration>
</execution>
</executions>
</plugin>
```
Sometimes you also need to care about the static constructors used in some libraries (for example, database drivers). You need to call [`Class.forName()`](https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html#forName-java.lang.String-) method to invoke the corresponding static constructor (for example `Class.forName("com.microsoft.sqlserver.jdbc.SQLServerDriver");`).
## General Data Types
You are free to use all the data types in Java for the input and output data, including native types; customized POJO types and specialized Azure types defined in `azure-functions-java-library` package. And Azure Functions runtime will try its best to convert the actual input value to the type you need (for example, a `String` input will be treated as a JSON string and be parsed to a POJO type defined in your code).
The POJO types you defined have the same accessible requirements as the function methods, it needs to be `public` accessible. While the POJO class fields are not; for example a JSON string `{ "x": 3 }` is able to be converted to the following POJO type:
```Java
public class MyData {
private int x;
}
```
Binary data is represented as `byte[]` or `Byte[]` in your Azure functions code. And make sure you specify `dataType = "binary"` in the corresponding triggers/bindings.
Empty input values could be `null` as your functions argument, but a recommended way to deal with potential empty values is to use `Optional<T>` type.
## Inputs
Inputs are divided into two categories in Azure Functions: one is the trigger input and the other is the additional input. Trigger input is the input who triggers your function. And besides that, you may also want to get inputs from other sources (like a blob), that is the additional input.
Let's take the following code snippet as an example:
```Java
package com.example;
import com.microsoft.azure.functions.annotation.*;
public class MyClass {
@FunctionName("echo")
public static String echo(
@HttpTrigger(name = "req", methods = { "put" }, authLevel = AuthorizationLevel.ANONYMOUS, route = "items/{id}") String in,
@TableInput(name = "item", tableName = "items", partitionKey = "Example", rowKey = "{id}", connection = "AzureWebJobsStorage") MyObject obj
) {
return "Hello, " + in + " and " + obj.getKey() + ".";
}
public static class MyObject {
public String getKey() { return this.RowKey; }
private String RowKey;
}
}
```
When this function is invoked, the HTTP request payload will be passed as the `String` for argument `in`; and one entry will be retrieved from the Azure Table Storage and be passed to argument `obj` as `MyObject` type.
## Outputs
Outputs can be expressed in return value or output parameters. If there is only one output, you are recommended to use the return value. For multiple outputs, you have to use **output parameters**.
Return value is the simplest form of output, you just return the value of any type, and Azure Functions runtime will try to marshal it back to the actual type (such as an HTTP response). You could apply any *output annotations* to the function method (the `name` property of the annotation has to be `$return`) to define the return value output.
For example, a blob content copying function could be defined as the following code. `@StorageAccount` annotation is used here to prevent the duplicating of the `connection` property for both `@BlobTrigger` and `@BlobOutput`.
```Java
package com.example;
import com.microsoft.azure.functions.annotation.*;
public class MyClass {
@FunctionName("copy")
@StorageAccount("AzureWebJobsStorage")
@BlobOutput(name = "$return", path = "samples-output-java/{name}")
public static String copy(@BlobTrigger(name = "blob", path = "samples-input-java/{name}") String content) {
return content;
}
}
```
To produce multiple output values, use `OutputBinding<T>` type defined in the `azure-functions-java-library` package. If you need to make an HTTP response and push a message to a queue, you can write something like:
```Java
package com.example;
import com.microsoft.azure.functions.*;
import com.microsoft.azure.functions.annotation.*;
public class MyClass {
@FunctionName("push")
public static String push(
@HttpTrigger(name = "req", methods = { "post" }, authLevel = AuthorizationLevel.ANONYMOUS) String body,
@QueueOutput(name = "message", queueName = "myqueue", connection = "AzureWebJobsStorage") OutputBinding<String> queue
) {
queue.setValue("This is the queue message to be pushed");
return "This is the HTTP response content";
}
}
```
Of course you could use `OutputBinding<byte[]>` type to make a binary output value (for parameters); for return values, just use `byte[]`.
## Execution Context
You interact with Azure Functions execution environment via the `ExecutionContext` object defined in the `azure-functions-java-library` package. You are able to get the invocation ID, the function name and a built-in logger (which is integrated prefectly with Azure Function Portal experience as well as AppInsights) from the context object.
What you need to do is just add one more `ExecutionContext` typed parameter to your function method. Let's take a timer triggered function as an example:
```Java
package com.example;
import com.microsoft.azure.functions.*;
import com.microsoft.azure.functions.annotation.*;
public class MyClass {
@FunctionName("heartbeat")
public static void heartbeat(
@TimerTrigger(name = "schedule", schedule = "*/30 * * * * *") String timerInfo,
ExecutionContext context
) {
context.getLogger().info("Heartbeat triggered by " + context.getFunctionName());
}
}
```
## Specialized Data Types
### HTTP Request and Response
Sometimes a function need to take a more detailed control of the input and output, and that's why we also provide some specialized types in the `azure-functions-java-library` package for you to manipulate:
| Specialized Type | Target | Typical Usage |
| ------------------------ | :-----------------: | ------------------------------ |
| `HttpRequestMessage<T>` | HTTP Trigger | Get method, headers or queries |
| `HttpResponseMessage<T>` | HTTP Output Binding | Return status other than 200 |
### Metadata
Metadata comes from different sources, like HTTP headers, HTTP queries, and [trigger metadata](https://docs.microsoft.com/en-us/azure/azure-functions/functions-triggers-bindings#trigger-metadata-properties). You can use `@BindingName` annotation together with the metadata name to get the value.
For example, the `queryValue` in the following code snippet will be `"test"` if the requested URL is `http://{example.host}/api/metadata?name=test`.
```Java
package com.example;
import java.util.Optional;
import com.microsoft.azure.functions.annotation.*;
public class MyClass {
@FunctionName("metadata")
public static String metadata(
@HttpTrigger(name = "req", methods = { "get", "post" }, authLevel = AuthorizationLevel.ANONYMOUS) Optional<String> body,
@BindingName("name") String queryValue
) {
return body.orElse(queryValue);
}
}
```

32
appveyor.yml Normal file
Просмотреть файл

@ -0,0 +1,32 @@
version: '{build}'
image: Visual Studio 2017
pull_requests:
do_not_increment_build_number: true
branches:
only:
- dev
- master
environment:
matrix:
- JAVA_HOME: C:\Program Files\Java\jdk1.8.0
install:
- cmd: echo %JAVA_HOME%
- ps: Get-Command mvn
- cmd: mvn -v
- ps: Get-Command nuget
build_script:
- mvn clean install -DskipTests
- ps: mkdir .pkg
artifacts:
- path: '*.nupkg'
- path: 'azure-functions-java-library/target/**.jar'
cache:
- C:\maven\

87
pom.xml
Просмотреть файл

@ -1,86 +1,11 @@
<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/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.microsoft.azure</groupId>
<artifactId>azure-functions-java-core</artifactId>
<version>1.0.0-beta-2</version>
<groupId>com.microsoft.azure.functions</groupId>
<artifactId>azure-functions-java-library</artifactId>
<version>1.0.0-beta-4</version>
<packaging>jar</packaging>
<name>Microsoft Azure Functions Java Core Types</name>
<description>This package contains all Java interfaces and annotations to interact with Microsoft Azure functions runtime.</description>
<url>https://azure.microsoft.com/en-us/services/functions</url>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<licenses>
<license>
<name>MIT License</name>
<url>https://opensource.org/licenses/MIT</url>
<distribution>repo</distribution>
</license>
</licenses>
<scm>
<connection>scm:git:https://github.com/Azure/azure-functions-java-worker</connection>
<developerConnection>scm:git:git@github.com:Azure/azure-functions-java-worker</developerConnection>
<url>https://github.com/Azure/azure-functions-java-worker</url>
<tag>HEAD</tag>
</scm>
<developers>
<developer>
<id>junyi</id>
<name>Junyi Yi</name>
<email>junyi@microsoft.com</email>
</developer>
<developer>
<id>xscript</id>
<name>Kevin Zhao</name>
<email>kevinzha@microsoft.com</email>
</developer>
</developers>
<dependencies>
</dependencies>
<build>
<plugins>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.7.0</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>3.0.1</version>
<executions>
<execution>
<id>attach-sources</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.0.0-M1</version>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
<name>Microsoft Azure Functions Java Runtime Solution</name>
<description>This solution builds both the Java core types as well as the runtime for Microsoft Azure Functions.</description>
<url>https://azure.microsoft.com/en-us/services/functions</url>
</project>

Просмотреть файл

@ -1,4 +1,4 @@
package com.microsoft.azure.serverless.functions;
package com.microsoft.azure.functions;
import java.util.logging.Logger;

Просмотреть файл

@ -1,4 +1,4 @@
package com.microsoft.azure.serverless.functions;
package com.microsoft.azure.functions;
import java.net.URI;
import java.util.Map;

Просмотреть файл

@ -1,4 +1,4 @@
package com.microsoft.azure.serverless.functions;
package com.microsoft.azure.functions;
public interface HttpResponseMessage<T> {
int getStatus();

Просмотреть файл

@ -1,4 +1,4 @@
package com.microsoft.azure.serverless.functions;
package com.microsoft.azure.functions;
public interface OutputBinding<T> {
T getValue();

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
public enum AccessRights {
MANAGE,

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
public enum AuthorizationLevel {
ANONYMOUS,

Просмотреть файл

@ -1,4 +1,4 @@
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;

Просмотреть файл

@ -4,7 +4,7 @@
* license information.
*/
package com.microsoft.azure.serverless.functions.annotation;
package com.microsoft.azure.functions.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;