Added the first cut of the Java interface for Pulsar functions (#2)

pulsar-functions/src/main/java/org/apache/pulsar/functions/api/Context.java

@@ -0,0 +1,85 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Context provides contextual information to the executing function.
+ * Features like which message id we are handling, whats the topic name of the
+ * message, what are our operating constraints, etc can be accessed by the
+ * executing function
+ */
+package org.apache.pulsar.functions.api;
+
+import org.slf4j.Logger;
+
+interface Context {
+    /**
+     * Returns the messageId of the message that we are processing
+     * This messageId is a stringified version of the actual MessageId
+     * @return the messageId
+     */
+    String getMessageId();
+
+    /**
+     * The topic that this message belongs to
+     * @return The topic name
+     */
+    String getTopicName();
+
+    /**
+     * The name of the function that we are executing
+     * @return The Function name
+     */
+    String getFunctionName();
+
+    /**
+     * The id of the function that we are executing
+     * @return The function id
+     */
+    String getFunctionId();
+
+    /**
+     * The version of the function that we are executing
+     * @return The version id
+     */
+    String getFunctionVersion();
+
+    /**
+     * The memory limit that this function is limited to
+     * @return Memory limit in bytes
+     */
+    long getMemoryLimit();
+
+    /**
+     * The time budget in ms that the function is limited to.
+     * @return Time budget in msecs.
+     */
+    long getTimeBudgetInMs();
+
+    /**
+     * The time in ms remaining for this function execution to complete before it
+     * will be flagged as an error
+     * @return Time remaining in ms.
+     */
+    long getRemainingTimeInMs();
+
+    /**
+     * The logger object that can be used to log in a function
+     * @return the logger object
+     */
+    Logger getLogger();
+}

pulsar-functions/src/main/java/org/apache/pulsar/functions/api/RawRequestHandler.java

@@ -0,0 +1,37 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * This is the more generic function interface compared to the RequestHandler.
+ * The handleRequest is called for every message of the input topic of the function.
+ * The incoming input bytes can be accessed via the InputStream. Users can then
+ * deserialize this in any way they want before processing. Any output goes into
+ * OutputStream.
+ */
+package org.apache.pulsar.functions.api;
+
+import java.io.InputStream;
+import java.io.OutputStream;
+
+interface RawRequestHandler {
+    /**
+     * Process the input coming as an input stream. The process function
+     * can optionally output any bytes into the Outputstream output.
+     */
+    void handleRequest(InputStream input, OutputStream output, Context context) throws Exception;
+}

pulsar-functions/src/main/java/org/apache/pulsar/functions/api/RequestHandler.java

@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * This is the core interface of the function api. The handleRequest is called
+ * for every message of the input topic of the function. The incoming input bytes
+ * are converted to the input type I for simple Java types(String, Integer, Boolean,
+ * Map, and List types) and for org.Json type. If this serialization approach does not
+ * meet your needs, you can use the byte stream handler defined in RawRequestHandler.
+ */
+package org.apache.pulsar.functions.api;
+
+interface RequestHandler<I, O> {
+    /**
+     * Process the input.
+     * @return the output
+     */
+    O handleRequest(I input, Context context) throws Exception;
+}