Merge pull request #38 from JunyiYi/add_samples

Add verified samples for P1 bindings/triggers

src/main/java/com/microsoft/azure/functions/annotation/BlobInput.java

@@ -20,7 +20,23 @@
  *     <li>Any POJO type</li>
  * </ul>
  *
- *
+ * <p>The following example is a Java function that uses a queue trigger and an input blob binding. The queue message
+ * contains the name of the blob, and the function logs the size of the blob.</p>
+ * 
+ * <pre>{@literal @}FunctionName("getBlobSize")
+ *{@literal @}StorageAccount("AzureWebJobsStorage")
+ * public void blobSize(
+ *    {@literal @}QueueTrigger(name = "filename",
+ *                   queueName = "myqueue-items") String filename,
+ *    {@literal @}BlobInput(name = "file",
+ *                dataType = "binary",
+ *                path = "samples-workitems/{queueTrigger}") byte[] content,
+ *     final ExecutionContext context
+ * ) {
+ *     context.getLogger().info("The size of \"" + filename + "\" is: " + content.length + " bytes");
+ * }</pre>
+ * 
+ * 
  * @since 1.0.0
  */
 @Retention(RetentionPolicy.RUNTIME)

src/main/java/com/microsoft/azure/functions/annotation/BlobOutput.java

@@ -20,6 +20,21 @@
  *     <li>Any POJO type</li>
  * </ul>
  *
+ * <p>The following example shows blob input and output bindings in a Java function. The function makes a copy of
+ * a text blob. The function is triggered by a queue message that contains the name of the blob to copy. The new
+ * blob is named {originalblobname}-Copy.</p>
+ * 
+ * <pre>{@literal @}FunctionName("copyTextBlob")
+ *{@literal @}StorageAccount("AzureWebJobsStorage")
+ *{@literal @}BlobOutput(name = "target", path = "samples-workitems/{queueTrigger}-Copy")
+ * public String blobCopy(
+ *    {@literal @}QueueTrigger(name = "filename",
+ *                   queueName = "myqueue-items") String filename,
+ *    {@literal @}BlobInput(name = "source",
+ *                path = "samples-workitems/{queueTrigger}") String content
+ * ) {
+ *     return content;
+ * }</pre>
  *
  * @since 1.0.0
  */

src/main/java/com/microsoft/azure/functions/annotation/BlobTrigger.java

@@ -22,18 +22,19 @@
  * </ul>
  *
  *
- * <p>The following example shows a storage blob trigger which logs the blob filename as well as its size:</p>
+ * <p>The following example shows a Java function that logs the filename and size when a blob is added or updated
+ * in the "samples-workitems" container:</p>
  *
- * <pre>{@literal @}FunctionName("blobprocessor")
- * public void run(
+ * <pre>{@literal @}FunctionName("blobMonitor")
+ * public void blobMonitor(
  *    {@literal @}BlobTrigger(name = "file",
  *                  dataType = "binary",
- *                  path = "myblob/filepath",
- *                  connection = "myconnvarname") byte[] content,
+ *                  path = "samples-workitems/{name}",
+ *                  connection = "AzureWebJobsStorage") byte[] content,
  *    {@literal @}BindingName("name") String filename,
  *     final ExecutionContext context
  * ) {
- *     context.getLogger().info("Name: " + name + " Size: " + content.length + " bytes");
+ *     context.getLogger().info("Name: " + filename + ", Size: " + content.length + " bytes");
  * }</pre>
  *
  * @see com.microsoft.azure.functions.annotation.BindingName

src/main/java/com/microsoft/azure/functions/annotation/EventHubOutput.java

@@ -20,6 +20,15 @@
  *     <li>Any POJO type</li>
  * </ul>
  *
+ * <p>The following example shows a Java function that writes a message to an event hub:</p>
+ * 
+ * <pre>{@literal @}FunctionName("sendTime")
+ *{@literal @}EventHubOutput(name = "event", eventHubName = "samples-workitems", connection = "AzureEventHubConnection")
+ * public String sendTime(
+ *    {@literal @}TimerTrigger(name = "sendTimeTrigger", schedule = "0 *&#47;5 * * * *") String timerInfo
+ * ) {
+ *     return LocalDateTime.now().toString();
+ * }</pre>
  *
  * @since 1.0.0
  */

src/main/java/com/microsoft/azure/functions/annotation/EventHubTrigger.java

@@ -21,16 +21,14 @@
  *     <li>Any POJO type</li>
  * </ul>
  *
- * <p>The following example shows an event hub trigger which logs the message:</p>
+ * <p>The following example shows a Java function that logs the message body of the event hub trigger:</p>
  *
- * <pre>{@literal @}FunctionName("ehprocessor")
- * public void eventHubProcessor(
- *    {@literal @}EventHubTrigger(name = "msg",
- *                      eventHubName = "myeventhubname",
- *                      connection = "myconnvarname") String message,
+ * <pre>{@literal @}FunctionName("eventHubMonitor")
+ * public void logEventHubMessage(
+ *    {@literal @}EventHubTrigger(name = "event", eventHubName = "samples-workitems", connection = "AzureEventHubConnection") String message,
  *     final ExecutionContext context
  * ) {
- *     context.getLogger().info(message);
+ *     context.getLogger().info("Event hub message received: " + message);
  * }</pre>
  *
  * @since 1.0.0

src/main/java/com/microsoft/azure/functions/annotation/HttpTrigger.java

@@ -32,8 +32,9 @@
  * {@literal @}FunctionName("hello")
  *  public HttpResponseMessage<String> helloFunction(
  *    {@literal @}HttpTrigger(name = "req",
- *                  methods = {"get"},
- *                  authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request) {
+ *                  methods = {HttpMethod.GET},
+ *                  authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request
+ *  ) {
  *     ....
  *  }</pre>
  *
@@ -54,6 +55,35 @@
  * endpoints to be specified, and for these endpoints to be parameterized with arguments being bound to arguments
  * provided to the function at runtime.</p>
  *
+ * <p>The following example shows a Java function that looks for a name parameter either in the query string (HTTP GET)
+ * or the body (HTTP POST) of the HTTP request. Notice that the return value is used for the output binding, but a return
+ * value attribute isn't required.</p>
+ * 
+ * <pre>
+ * {@literal @}FunctionName("readHttpName")
+ *  public String readName(
+ *    {@literal @}HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
+ *     final HttpRequestMessage&lt;Optional&lt;String&gt;&gt; request
+ *  ) {
+ *       String name = request.getBody().orElseGet(() -&gt; request.getQueryParameters().get("name"));
+ *       return name == null ?
+ *              "Please pass a name on the query string or in the request body" :
+ *              "Hello " + name;
+ *  }</pre>
+ * 
+ * <p>The following example shows a webhook trigger binding in Java function. The function logs GitHub issue comments.</p>
+ * 
+ * <pre>
+ * {@literal @}FunctionName("logGithubIssues")
+ *  public String logIssues(
+ *    {@literal @}HttpTrigger(name = "req", webHookType = WebHookType.GITHUB) final String content,
+ *     ExecutionContext context
+ *  ) {
+ *       context.getLogger().info("WebHook was triggered!");
+ *       context.getLogger().info("Content is " + content);
+ *       return "New GitHub comment: " + content;
+ *  }</pre>
+ * 
  * @see com.microsoft.azure.functions.HttpRequestMessage
  * @see com.microsoft.azure.functions.HttpResponseMessage
  * @since 1.0.0
@@ -96,12 +126,13 @@
      * {@literal @}FunctionName("routeTest")
      *  public HttpResponseMessage&lt;String&gt; routeTest(
      *      {@literal @}HttpTrigger(name = "req",
-     *                    methods = {"get"},
+     *                    methods = {HttpMethod.GET},
      *                    authLevel = AuthorizationLevel.ANONYMOUS,
      *                    route = "products/{category:alpha}/{id:int}") HttpRequestMessage&lt;Optional&lt;String&gt;&gt; request,
      *      {@literal @}BindingName("category") String category,
      *      {@literal @}BindingName("id") int id,
-     *       final ExecutionContext context) {
+     *       final ExecutionContext context
+     *  ) {
      *           ....
      *           context.getLogger().info("We have " + category + " with id " + id);
      *           ....

src/main/java/com/microsoft/azure/functions/annotation/QueueOutput.java

@@ -20,6 +20,18 @@
  *     <li>Any POJO type</li>
  * </ul>
  *
+ * <p>The following example shows a Java function that creates a queue message for each HTTP request received.</p>
+ * 
+ * <pre>{@literal @}FunctionName("httpToQueue")
+ *{@literal @}QueueOutput(name = "item", queueName = "myqueue-items", connection = "AzureWebJobsStorage")
+ * public String pushToQueue(
+ *    {@literal @}HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
+ *     final String message,
+ *    {@literal @}HttpOutput(name = "response") final OutputBinding&lt;String&gt; result
+ * ) {
+ *     result.setValue(message + " has been added.");
+ *     return message;
+ * }</pre>
  *
  * @since 1.0.0
  */

src/main/java/com/microsoft/azure/functions/annotation/QueueTrigger.java

@@ -21,16 +21,15 @@
  *     <li>Any POJO type</li>
  * </ul>
  *
- * <p>The following example shows a storage queue trigger which logs the message:</p>
+ * <p>The following example shows a Java function that polls the "myqueue-items" queue and writes a log each time a
+ * queue item is processed.</p>
  *
- * <pre>{@literal @}FunctionName("queueprocessor")
- * public void run(
- *    {@literal @}QueueTrigger(name = "msg",
- *                   queueName = "myqueuename",
- *                   connection = "myconnvarname") String message,
+ * <pre>{@literal @}FunctionName("queueMonitor")
+ * public void logQueueItem(
+ *    {@literal @}QueueTrigger(name = "msg", queueName = "myqueue-items", connection = "AzureWebJobsStorage") String message,
  *     final ExecutionContext context
  * ) {
- *     context.getLogger().info(message);
+ *     context.getLogger().info("Queue message processed: " + message);
  * }</pre>
  *
  * @since 1.0.0

src/main/java/com/microsoft/azure/functions/annotation/ServiceBusQueueOutput.java

@@ -20,6 +20,18 @@
  *     <li>Any POJO type</li>
  * </ul>
  *
+ * <p>The following example shows a Java function that sends a Service Bus queue message:</p>
+ *
+ * <pre>{@literal @}FunctionName("httpToServiceBusQueue")
+ *{@literal @}ServiceBusQueueOutput(name = "message", queueName = "myqueue", connection = "AzureServiceBusConnection")
+ * public String pushToQueue(
+ *    {@literal @}HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
+ *     final String message,
+ *    {@literal @}HttpOutput(name = "response") final OutputBinding&lt;String&gt; result
+ * ) {
+ *     result.setValue(message + " has been sent.");
+ *     return message;
+ * }</pre>
  *
  * @since 1.0.0
  */

src/main/java/com/microsoft/azure/functions/annotation/ServiceBusQueueTrigger.java

@@ -21,16 +21,14 @@
  *     <li>Any POJO type</li>
  * </ul>
  *
- * <p>The following example shows a service bus queue trigger which logs the queue message:</p>
+ * <p>The following example shows a Java function that logs a Service Bus queue message:</p>
  *
- * <pre>{@literal @}FunctionName("sbprocessor")
- * public void serviceBusProcess(
- *    {@literal @}ServiceBusQueueTrigger(name = "msg",
- *                             queueName = "myqueuename",
- *                             connection = "myconnvarname") String message,
+ * <pre>{@literal @}FunctionName("serviceBusMonitor")
+ * public void logServiceBusMessage(
+ *    {@literal @}ServiceBusQueueTrigger(name = "msg", queueName = "myqueue", connection = "AzureServiceBusConnection") final String message,
  *     final ExecutionContext context
  * ) {
- *     context.getLogger().info(message);
+ *     context.getLogger().info("Message is received: " + message);
  * }</pre>
  *
  * @since 1.0.0

src/main/java/com/microsoft/azure/functions/annotation/TimerTrigger.java

@@ -17,12 +17,16 @@
  * this annotation.
  *
  * <p>An example of using the timer trigger is shown below, where the {@code keepAlive} function is set to trigger and
- * execute every four minutes:</p>
+ * execute every five minutes:</p>
  *
- * <pre>
- * {@literal @}FunctionName("keepAlive")
- *  public void keepAlive(@TimerTrigger(name = "keepAliveTrigger", schedule = "0 *&#47;4 * * * *") String timerInfo) { .. }
- * </pre>
+ * <pre>{@literal @}FunctionName("keepAlive")
+ * public void keepAlive(
+ *    {@literal @}TimerTrigger(name = "keepAliveTrigger", schedule = "0 *&#47;5 * * * *") String timerInfo,
+ *     ExecutionContext context
+ * ) {
+ *     // timeInfo is a JSON string, you can deserialize it to an object using your favorite JSON library
+ *     context.getLogger().info("Timer is triggered: " + timerInfo);
+ * }</pre>
  *
  * @since 1.0.0
  */