New preview introduces new annotations (Azure#87)

* Format xml with syntax highlighting in readme.md

* A few improvements to the JavaDoc for Azure Functions / Java

* Further updates to JavaDocs for Azure Functions Java API. Not complete, but a good starting point.

* Updates to javadoc based on review feedback

* Small tweaks based on PR review

* Update readme.md file to remove shade advice

Shade advice is no longer recommended practice, so removing from the readme.md file before it leads to additional confusion.

* Update README.md

Add details about the funcitonLib property requirement.

* Increase both core and worker version since both of them will be updated.

* Remove the unnecessary variable definition.

* change documentdb to cosmosdb

* add cosmosdb trigger

* add cosmosDBTrigger binding defination

* add eventgrid support

* Add convenient method of createResponse with empty body.

* Add development documentation on how to build and debug.

* Add javadoc generation instruction.

* Add unit test framework to the project.

* Rename package names of testing categories.

* Add GRPC e2e test framework as well as test cases.

README.md

@@ -33,47 +33,19 @@ public class MyClass {
 
 ### Including 3rd Party Libraries
 
-Azure Functions supports the following for referencing dependencies:
+Azure Functions supports the use of 3rd party libraries. This is achieved by extending your build script to copy all dependencies to a lib folder in the function's root directory, which will then be deployed as part of your functions application. All dependencies that are placed in the `lib` directory will be added to the system class loader at runtime. 
 
-1. Creating a single JAR file.
-2. Copying all dependencies to a lib folder in the function's root directory
-
-#### 1. Single JAR
-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`:
+Adding the following to your Maven `pom.xml` will copy all your dependencies to the Function App's `lib` directory. There are two changes required - configuring a property, and configuring the `maven-dependency-plugin`. 
 
+In the properties section of your `pom.xml` file, you need to set the `functionLib` property as such:
 ```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>
+<properties>
+    <functionLib>${project.build.directory}/azure-functions/${functionAppName}/lib</functionLib>
+</properties>
 ```
 
-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");`).
-
-#### 2. Dependencies in the lib/ folder
-All dependencies that are placed in the `lib` directory will be added to the system class loader at runtime. Add the following plugin definition to your `pom.xml`:
-
-```
+In the plugins section of your `pom.xml` file, you need to configure the `maven-dependency-plugin` as such:
+```xml
 <plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-dependency-plugin</artifactId>
@@ -95,7 +67,8 @@ All dependencies that are placed in the `lib` directory will be added to the sys
   </executions>
 </plugin>
 ```
-This will copy all your dependencies to the Function App's `lib` directory. Be sure to package and deploy the lib as part of the Function App.
+
+Finally, be sure to package and deploy the lib as part of the Function App.
 
 ## General Data Types
 

azure-functions-java-core/pom.xml

@@ -2,7 +2,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.microsoft.azure</groupId>
   <artifactId>azure-functions-java-core</artifactId>
-  <version>1.0.0-beta-2</version>
+  <version>1.0.0-beta-3</version>
   <packaging>jar</packaging>
 
   <name>Microsoft Azure Functions Java Core Types</name>

azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/ExecutionContext.java

@@ -2,8 +2,30 @@
 
 import java.util.logging.Logger;
 
+/**
+ * The execution context enables interaction with the Azure Functions execution environment.
+ *
+ * @since 1.0.0
+ */
 public interface ExecutionContext {
+    /**
+     * Returns the built-in logger, which is integrated with the logging functionality provided in the Azure Functions
+     * portal, as well as in Azure Application Insights.
+     *
+     * @return A Java logger that will see output directed to Azure Portal, as well as any other configured output
+     *      locations.
+     */
     Logger getLogger();
+
+    /**
+     * Returns the invocation ID for the function call.
+     * @return the invocation ID for the function call.
+     */
     String getInvocationId();
+
+    /**
+     * Returns the function name.
+     * @return the function name.
+     */
     String getFunctionName();
 }

azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/HttpRequestMessage.java

@@ -3,12 +3,65 @@
 import java.net.URI;
 import java.util.Map;
 
+/**
+ * An HttpRequestMessage instance is provided to Azure functions that use
+ * {@link com.microsoft.azure.serverless.functions.annotation.HttpTrigger HTTP Triggers}. For an example of how to use
+ * the http functionality of Azure Functions, refer to the example in the
+ * {@link com.microsoft.azure.serverless.functions.annotation.HttpTrigger}
+ *
+ * @see com.microsoft.azure.serverless.functions.annotation.HttpTrigger
+ * @see HttpResponseMessage
+ * @param <T> The type of the body content that is expected to be received as part of this HTTP request.
+ * @since 1.0.0
+ */
 public interface HttpRequestMessage<T> {
+    /**
+     * Returns the URI that was called that resulted in this HTTP request being submitted.
+     * @return the URI that was called that resulted in this HTTP request being submitted.
+     */
     URI getUri();
+
+    /**
+     * Returns the HTTP method name, such as "GET" and "POST".
+     * @return the HTTP method name, such as "GET" and "POST".
+     */
     String getMethod();
+
+    /**
+     * Returns a map of headers that were contained within this HTTP request.
+     * @return a map of headers that were contained within this HTTP request.
+     */
     Map<String, String> getHeaders();
+
+    /**
+     * Returns a map of query parameters that were included with this HTTP request.
+     * @return a map of query parameters that were included with this HTTP request.
+     */
     Map<String, String> getQueryParameters();
+
+    /**
+     * Returns any body content that was included with this HTTP request.
+     * @return any body content that was included with this HTTP request.
+     */
     T getBody();
 
+    /**
+     * Generates a {@link HttpResponseMessage} instance containing the given HTTP status code and no response body.
+     * Additional headers may be added by calling appropriate methods on {@link HttpResponseMessage}.
+     *
+     * @param status The HTTP status code to return to the caller of the function.
+     * @return An {@link HttpResponseMessage} instance containing the provided status and empty body.
+     */
+    HttpResponseMessage<Object> createResponse(int status);
+
+    /**
+     * Generates a {@link HttpResponseMessage} instance containing the given HTTP status code and response body.
+     * Additional headers may be added by calling appropriate methods on {@link HttpResponseMessage}.
+     *
+     * @param status The HTTP status code to return to the caller of the function.
+     * @param body The body content to return to the caller of the function.
+     * @param <R> The type of the body, as determined by the return type specified on the function itself.
+     * @return An {@link HttpResponseMessage} instance containing the provided status and body content.
+     */
     <R> HttpResponseMessage<R> createResponse(int status, R body);
 }

azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/HttpResponseMessage.java

@@ -1,10 +1,51 @@
 package com.microsoft.azure.serverless.functions;
 
+/**
+ * An HttpResponseMessage instance is returned by Azure Functions methods that are triggered by an
+ * {@link com.microsoft.azure.serverless.functions.annotation.HttpTrigger}.
+ *
+ * @see com.microsoft.azure.serverless.functions.annotation.HttpTrigger
+ * @see HttpRequestMessage
+ * @param <T> The type of the body, as determined by the return type specified on the function itself.
+ * @since 1.0.0
+ */
 public interface HttpResponseMessage<T> {
+
+    /**
+     * Returns the status code set on the HttpResponseMessage instance.
+     * @return the status code set on the HttpResponseMessage instance.
+     */
     int getStatus();
+
+    /**
+     * Sets the status code on the HttpResponseMessage instance.
+     * @param status An HTTP status code representing the outcome of the HTTP request.
+     */
     void setStatus(int status);
+
+    /**
+     * Adds a (key,value) header to the response.
+     * @param key The key of the header value.
+     * @param value The value of the header value.
+     */
     void addHeader(String key, String value);
+
+    /**
+     * Returns a header value for the given key.
+     * @param key The key for which the header value is sought.
+     * @return Returns the value if the key has previously been added, or null if it has not.
+     */
     String getHeader(String key);
+
+    /**
+     * Returns the body of the HTTP response.
+     * @return the body of the HTTP response.
+     */
     T getBody();
+
+    /**
+     * Sets the body of the HTTP response.
+     * @param body The body of the HTTP response
+     */
     void setBody(T body);
 }

azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/OutputBinding.java

@@ -1,5 +1,9 @@
 package com.microsoft.azure.serverless.functions;
 
+/**
+ *
+ * @since 1.0.0
+ */
 public interface OutputBinding<T> {
     T getValue();
     void setValue(T value);

azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/annotation/AccessRights.java

@@ -6,6 +6,10 @@
 
 package com.microsoft.azure.serverless.functions.annotation;
 
+/**
+ *
+ * @since 1.0.0
+ */
 public enum AccessRights {
     MANAGE,
     LISTEN

azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/annotation/ApiHubFileInput.java

@@ -11,6 +11,10 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ *
+ * @since 1.0.0
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.PARAMETER)
 public @interface ApiHubFileInput {

azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/annotation/ApiHubFileOutput.java

@@ -11,6 +11,10 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ *
+ * @since 1.0.0
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.PARAMETER, ElementType.METHOD})
 public @interface ApiHubFileOutput {

azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/annotation/ApiHubFileTrigger.java

@@ -11,6 +11,10 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ *
+ * @since 1.0.0
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.PARAMETER)
 public @interface ApiHubFileTrigger {

azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/annotation/AuthorizationLevel.java

@@ -6,6 +6,10 @@
 
 package com.microsoft.azure.serverless.functions.annotation;
 
+/**
+ *
+ * @since 1.0.0
+ */
 public enum AuthorizationLevel {
     ANONYMOUS,
     FUNCTION,

azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/annotation/BindingName.java

@@ -5,6 +5,10 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ *
+ * @since 1.0.0
+ */
 @Target(ElementType.PARAMETER)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface BindingName {

azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/annotation/BlobInput.java

@@ -11,6 +11,10 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ *
+ * @since 1.0.0
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.PARAMETER)
 public @interface BlobInput {

azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/annotation/BlobOutput.java

@@ -11,6 +11,10 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ *
+ * @since 1.0.0
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.PARAMETER, ElementType.METHOD})
 public @interface BlobOutput {

azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/annotation/BlobTrigger.java

@@ -11,6 +11,10 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ *
+ * @since 1.0.0
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.PARAMETER)
 public @interface BlobTrigger {

azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/annotation/DocumentDBInput.java → azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/annotation/CosmosDBInput.java

@@ -11,9 +11,13 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ *
+ * @since 1.0.0
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.PARAMETER)
-public @interface DocumentDBInput {
+public @interface CosmosDBInput {
     String name();
 
     String dataType() default "";
@@ -26,5 +30,5 @@
 
     String sqlQuery() default "";
 
-    String connection();
+    String connectionStringSetting();
 }

azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/annotation/DocumentDBOutput.java → azure-functions-java-core/src/main/java/com/microsoft/azure/serverless/functions/annotation/CosmosDBOutput.java

@@ -11,9 +11,13 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ *
+ * @since 1.0.0
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.PARAMETER, ElementType.METHOD})
-public @interface DocumentDBOutput {
+public @interface CosmosDBOutput {
     String name();
 
     String dataType() default "";
@@ -24,5 +28,5 @@
 
     boolean createIfNotExists() default false;
 
-    String connection();
+    String connectionStringSetting();
 }