001// Copyright 2019 Google LLC
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007//      http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package com.google.cloud.functions;
016
017/**
018 * Represents a Cloud Function that is activated by an event. The payload of the event is a JSON
019 * object, which can be parsed using a JSON package such as
020 * <a href="https://github.com/google/gson/blob/master/UserGuide.md">GSON</a>.
021 *
022 * <p>Here is an example of an implementation that parses the JSON payload using Gson, to access its
023 * {@code messageId} property:
024 *
025 * <!-- The {@code} placement is a bit strange here, to prevent spurious spaces introduced by the
026 *      javadoc tool. -->
027 * <pre>
028 * public class Example implements RawBackgroundFunction {
029 *   private static final Logger logger = Logger.getLogger(Example.class.getName());
030 *
031 *  {@code @Override}
032 *   public void accept(String json, Context context) {
033 *     JsonObject jsonObject = new Gson().fromJson(json, JsonObject.class);
034 *     JsonElement messageId = jsonObject.get("messageId");
035 *     String messageIdString = messageId.getAsJsonString();
036 *     logger.info("Got messageId " + messageIdString);
037 *   }
038 * }
039 * </pre>
040 *
041 * <p>Here is an example of an implementation that deserializes the JSON payload into a Java
042 * object for simpler access, again using Gson:
043 *
044 * <pre>
045 * public class Example implements RawBackgroundFunction {
046 *   private static final Logger logger = Logger.getLogger(Example.class.getName());
047 *
048 *  {@code @Override}
049 *   public void accept(String json, Context context) {
050 *     PubSubMessage message = new Gson().fromJson(json, PubSubMessage.class);
051 *     logger.info("Got messageId " + message.messageId);
052 *   }
053 * }
054 *
055 * // Where PubSubMessage is a user-defined class like this:
056 * public class PubSubMessage {
057 *   String data;
058 *  {@code Map<String, String>} attributes;
059 *   String messageId;
060 *   String publishTime;
061 * }
062 * </pre>
063 */
064@FunctionalInterface
065public interface RawBackgroundFunction {
066  /**
067   * Called to service an incoming event. This interface is implemented by user code to
068   * provide the action for a given background function. If this method throws any exception
069   * (including any {@link Error}) then the HTTP response will have a 500 status code.
070   *
071   * @param json the payload of the event, as a JSON string.
072   * @param context the context of the event. This is a set of values that every event has,
073   *     separately from the payload, such as timestamp and event type.
074   * @throws Exception to produce a 500 status code in the HTTP response.
075   */
076  void accept(String json, Context context) throws Exception;
077}