SLING-5643 Provide a simple messaging API
authorOliver Lietz <olli@apache.org>
Thu, 7 Apr 2016 09:17:29 +0000 (09:17 +0000)
committerOliver Lietz <olli@apache.org>
Thu, 7 Apr 2016 09:17:29 +0000 (09:17 +0000)
git-svn-id: https://svn.apache.org/repos/asf/sling/trunk@1738113 13f79535-47bb-0310-9956-ffa450edef68

README.md [new file with mode: 0644]
pom.xml [new file with mode: 0644]
src/main/java/org/apache/sling/commons/messaging/Failure.java [new file with mode: 0644]
src/main/java/org/apache/sling/commons/messaging/MessageService.java [new file with mode: 0644]
src/main/java/org/apache/sling/commons/messaging/Result.java [new file with mode: 0644]
src/main/java/org/apache/sling/commons/messaging/package-info.java [new file with mode: 0644]

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..929c3a7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,23 @@
+Apache Sling Commons Messaging
+==============================
+
+Simple API for sending *message*​s to *recipient*​s.
+
+`MessageService`
+----------------
+  * `send(String, String)` - takes a *message*​ and a *recipient*, e.g.
+    * send("A Message to You, Rudy", "rudy@ghosttown") - send a mail to Rudy in Ghost Town
+    * send("Hello Apache!", "+1.919.573.9199") - send a fax to the ASF
+  * `send(String, String, Map)` - takes a *message*, a *recipient* and additional *data* useful for the underlying implementation to process and/or send the message
+
+`Result<T>`
+-----------
+  * `getMessage():T` - should return a serialized form of the sent *message*
+  * `hasFailures():boolean` - should return `true` in case of failures, `false` otherwise
+  * `getFailures():Collection<Failure>` - should return the failures occurred when processing or sending the message
+
+`Failure`
+---------
+ * `getCode():String` - should return a failure code when available, e.g. an [SMTP Status Code](https://tools.ietf.org/html/rfc5248)
+ * `getType():String` - should return a failure type when available, e.g. invalid input (message too big) or transport failure (host unavailable)
+ * `getMessage():String` - should return a human readable failure message
diff --git a/pom.xml b/pom.xml
new file mode 100644 (file)
index 0000000..7e456da
--- /dev/null
+++ b/pom.xml
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    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.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.apache.sling</groupId>
+    <artifactId>sling</artifactId>
+    <version>27-SNAPSHOT</version>
+    <relativePath/>
+  </parent>
+
+  <artifactId>org.apache.sling.commons.messaging</artifactId>
+  <version>0.0.1-SNAPSHOT</version>
+  <packaging>bundle</packaging>
+
+  <name>Apache Sling Commons Messaging</name>
+  <description>Apache Sling Commons Messaging</description>
+
+  <properties>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
+    <sling.java.version>8</sling.java.version>
+  </properties>
+
+  <scm>
+    <connection>scm:svn:http://svn.apache.org/repos/asf/sling/trunk/bundles/commons/org.apache.sling.commons.messaging</connection>
+    <developerConnection>scm:svn:https://svn.apache.org/repos/asf/sling/trunk/bundles/commons/org.apache.sling.commons.messaging</developerConnection>
+    <url>http://svn.apache.org/viewvc/sling/trunk/bundles/commons/org.apache.sling.commons.messaging</url>
+  </scm>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.felix</groupId>
+        <artifactId>maven-bundle-plugin</artifactId>
+        <extensions>true</extensions>
+      </plugin>
+    </plugins>
+  </build>
+
+  <dependencies>
+    <!-- OSGi -->
+    <dependency>
+      <groupId>org.osgi</groupId>
+      <artifactId>osgi.annotation</artifactId>
+      <version>6.0.1</version>
+      <scope>provided</scope>
+    </dependency>
+    <!-- JSR 305-->
+    <dependency>
+      <groupId>com.google.code.findbugs</groupId>
+      <artifactId>jsr305</artifactId>
+      <scope>provided</scope>
+    </dependency>
+  </dependencies>
+
+</project>
diff --git a/src/main/java/org/apache/sling/commons/messaging/Failure.java b/src/main/java/org/apache/sling/commons/messaging/Failure.java
new file mode 100644 (file)
index 0000000..9a5997b
--- /dev/null
@@ -0,0 +1,43 @@
+/*
+ * 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.
+ */
+package org.apache.sling.commons.messaging;
+
+import javax.annotation.CheckForNull;
+
+import org.osgi.annotation.versioning.ProviderType;
+
+@ProviderType
+public interface Failure {
+
+    /**
+     * @return a failure code when available
+     */
+    @CheckForNull String getCode();
+
+    /**
+     * @return a failure type when available
+     */
+    @CheckForNull String getType();
+
+    /**
+     * @return a human readable failure message
+     */
+    @CheckForNull String getMessage();
+
+}
diff --git a/src/main/java/org/apache/sling/commons/messaging/MessageService.java b/src/main/java/org/apache/sling/commons/messaging/MessageService.java
new file mode 100644 (file)
index 0000000..22e9763
--- /dev/null
@@ -0,0 +1,46 @@
+/*
+ * 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.
+ */
+package org.apache.sling.commons.messaging;
+
+import java.util.Map;
+import java.util.concurrent.Future;
+
+import javax.annotation.Nonnull;
+
+import org.osgi.annotation.versioning.ProviderType;
+
+@ProviderType
+public interface MessageService {
+
+    /**
+     * @param message   the message to send
+     * @param recipient the recipient of the message
+     * @return result of sending the message
+     */
+    Future<Result> send(@Nonnull final String message, @Nonnull final String recipient);
+
+    /**
+     * @param message   the message to send
+     * @param recipient the recipient of the message
+     * @param data      additional information (e.g. attachments) and/or parameters (e.g. sender) for the message
+     * @return result of sending the message
+     */
+    Future<Result> send(@Nonnull final String message, @Nonnull final String recipient, @Nonnull final Map data);
+
+}
diff --git a/src/main/java/org/apache/sling/commons/messaging/Result.java b/src/main/java/org/apache/sling/commons/messaging/Result.java
new file mode 100644 (file)
index 0000000..d335124
--- /dev/null
@@ -0,0 +1,45 @@
+/*
+ * 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.
+ */
+package org.apache.sling.commons.messaging;
+
+import java.util.Collection;
+
+import javax.annotation.CheckForNull;
+
+import org.osgi.annotation.versioning.ProviderType;
+
+@ProviderType
+public interface Result<T> {
+
+    /**
+     * @return serialized form of the sent message
+     */
+    @CheckForNull T getMessage();
+
+    /**
+     * @return <code>true</code> in case of failures, <code>false</code> otherwise
+     */
+    boolean hasFailures();
+
+    /**
+     * @return the failures occurred when processing or sending the message
+     */
+    @CheckForNull Collection<Failure> getFailures();
+
+}
diff --git a/src/main/java/org/apache/sling/commons/messaging/package-info.java b/src/main/java/org/apache/sling/commons/messaging/package-info.java
new file mode 100644 (file)
index 0000000..dee8a62
--- /dev/null
@@ -0,0 +1,22 @@
+/*
+ * 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.
+ */
+@Version("1.0.0")
+package org.apache.sling.commons.messaging;
+
+import org.osgi.annotation.versioning.Version;