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}