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 * <pre>
026 * public class Example implements RawBackgroundFunction {
027 *   private static final Logger logger = Logger.getLogger(Example.class.getName());
028 *
029 *   {@code @Override}
030 *   public void accept(String json, Context context) {
031 *     JsonObject jsonObject = new Gson().fromJson(json, JsonObject.class);
032 *     JsonElement messageId = jsonObject.get("messageId");
033 *     String messageIdString = messageId.getAsJsonString();
034 *     logger.info("Got messageId " + messageIdString);
035 *   }
036 * }
037 * </pre>
038 *
039 * <p>Here is an example of an implementation that deserializes the JSON payload into a Java
040 * object for simpler access, again using Gson:
041 *
042 * <pre>
043 * public class Example implements RawBackgroundFunction {
044 *   private static final Logger logger = Logger.getLogger(Example.class.getName());
045 *
046 *   {@code @Override}
047 *   public void accept(String json, Context context) {
048 *     PubSubMessage message = new Gson().fromJson(json, PubSubMessage.class);
049 *     logger.info("Got messageId " + message.messageId);
050 *   }
051 * }
052 *
053 * // Where PubSubMessage is a user-defined class like this:
054 * public class PubSubMessage {
055 *   String data;
056 *   {@code Map<String, String>} attributes;
057 *   String messageId;
058 *   String publishTime;
059 * }
060 * </pre>
061 */
062@FunctionalInterface
063public interface RawBackgroundFunction {
064  /**
065   * Called to service an incoming event. This interface is implemented by user code to
066   * provide the action for a given background function. If this method throws any exception
067   * (including any {@link Error}) then the HTTP response will have a 500 status code.
068   *
069   * @param json the payload of the event, as a JSON string.
070   * @param context the context of the event. This is a set of values that every event has,
071   *     separately from the payload, such as timestamp and event type.
072   */
073  void accept(String json, Context context) throws Exception;
074}