Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add a gateway client SDK for Kapua #701

Merged
merged 1 commit into from Jul 20, 2017
Merged

Add a gateway client SDK for Kapua #701

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
0 client/generate-client-java.sh → client/cloud/generate-client-java.sh
View file
Open in desktop
File renamed without changes.
26 changes: 26 additions & 0 deletions client/gateway/api/about.html
View file
Open in desktop
@@ -0,0 +1,26 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>

<title>About</title>
</head>
<body lang="EN-US">
<h2>About This Content</h2>

<p>June 27, 2017</p>
<h3>License</h3>

<p>The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise
indicated below, the Content is provided to you under the terms and conditions of the
Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available
at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>.
For purposes of the EPL, "Program" will mean the Content.</p>

<p>If you did not receive this Content directly from the Eclipse Foundation, the Content is
being redistributed by another party ("Redistributor") and different terms and conditions may
apply to your use of any object code in the Content. Check the Redistributor's license that was
provided with the Content. If no such license exists, contact the Redistributor. Unless otherwise
indicated below, the terms and conditions of the EPL still apply to any source code in the Content
and such source code may be obtained at <a href="http://www.eclipse.org/">http://www.eclipse.org</a>.</p>


</body></html>
51 changes: 51 additions & 0 deletions client/gateway/api/pom.xml
View file
Open in desktop
@@ -0,0 +1,51 @@
<?xml version="1.0" encoding="UTF-8"?>

<!--
Copyright (c) 2017 Red Hat Inc and others

All rights reserved. This program and the accompanying materials
are made available under the terms of the Eclipse Public License v1.0
which accompanies this distribution, and is available at
http://www.eclipse.org/legal/epl-v10.html

Contributors:
Red Hat Inc - initial API and implementation
-->

<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.eclipse.kapua</groupId>
<artifactId>kapua-client-gateway</artifactId>
<version>0.2.0-SNAPSHOT</version>
<relativePath>..</relativePath>
</parent>

<artifactId>kapua-client-gateway-api</artifactId>
<packaging>bundle</packaging>
<name>Eclipse Kapua :: Gateway Client :: API</name>
<description>The gateway client API definition</description>

<dependencies>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
</dependency>

<!-- testing dependencies -->
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<scope>test</scope>
</dependency>
</dependencies>

</project>
50 changes: 50 additions & 0 deletions client/gateway/api/src/main/java/org/eclipse/kapua/client/gateway/Application.java
View file
Open in desktop
@@ -0,0 +1,50 @@
/*******************************************************************************
* Copyright (c) 2017 Red Hat Inc and others.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Red Hat Inc - initial API and implementation
*******************************************************************************/
package org.eclipse.kapua.client.gateway;

/**
* An application is a sub-unit of a client, focused on handling data
* <p>
* The {@link Client} instance is more technical unit, where the {@link Application}
* is more a data oriented unit.
* </p>
*/
public interface Application extends AutoCloseable {

public interface Builder {

public Application build();
}

/**
* Lookup a data controller to an application topic
*
* @param topic
* the topic the controller is bound to, must never be {@code null}
* @return the data controller
*/
public Data data(Topic topic);

/**
* Lookup a transport controller
* <p>
* A transport controller for the client's underlying transport mechanism.
* </p>
* <p>
* <b>Note:</b> Each application has its own instance and thus can set
* events handler independent of the root client or other applications.
* </p>
*
* @return the transport controller
*/
public Transport transport();
}
53 changes: 53 additions & 0 deletions client/gateway/api/src/main/java/org/eclipse/kapua/client/gateway/BinaryPayloadCodec.java
View file
Open in desktop
@@ -0,0 +1,53 @@
/*******************************************************************************
* Copyright (c) 2017 Red Hat Inc and others.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Red Hat Inc - initial API and implementation
*******************************************************************************/
package org.eclipse.kapua.client.gateway;

import java.nio.ByteBuffer;

/**
* A codec for BLOB based payload transports
*/
public interface BinaryPayloadCodec {

/**
* Encode a {@link Payload} structure into a BLOB
* <p>
* The payload information gets encoded into a blob and appended at the end of the
* provided buffer. If the provided buffer is {@code null} a new buffer will be allocated.
* </p>
* <p>
* <b>Note:</b> The returning buffer may not be the same as the provided buffer. If the
* provided buffer has less remaining space than required a new buffer is allocated and
* returned, which will contain both the existing content as well as the newly appended.
* </p>
*
* @param payload
* The payload to encode, must not be {@code null}
* @param buffer
* An optional buffer to append the output to, may be {@code null}
* @return A buffer with the appended payload output, must never be {@code null}
* @throws Exception
* if anything goes wrong
*/
public ByteBuffer encode(Payload payload, ByteBuffer buffer) throws Exception;

/**
* Decode a {@link Payload} structure from the provided BLOB
*
* @param buffer
* The buffer to read from, must not be {@code null}
* @return the decoded payload structure, may be {@code null}
* @throws Exception
* if anything goes wrong
*/
public Payload decode(ByteBuffer buffer) throws Exception;
}
61 changes: 61 additions & 0 deletions client/gateway/api/src/main/java/org/eclipse/kapua/client/gateway/Client.java
View file
Open in desktop
@@ -0,0 +1,61 @@
/*******************************************************************************
* Copyright (c) 2017 Red Hat Inc and others.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Red Hat Inc - initial API and implementation
*******************************************************************************/
package org.eclipse.kapua.client.gateway;

/**
* A client connection
* <p>
* An instance of a client can be obtained by building and instance
* via different protocol stacks. e.g. see the {@code KuraMqttProfile}.
* </p>
* <p>
* In order to free resources the instance has to be closed when it is no
* longer needed.
* </p>
* <p>
* Data is exchanged by the use of {@link Application}s.
* </p>
*/
public interface Client extends AutoCloseable {

public interface Builder {

public Client build() throws Exception;
}

/**
* Get control over the transport
*
* @return The transport control instance
*/
public Transport transport();

/**
* Create a new application instance
* <p>
* This method only returns a new builder which will
* create a new instance once {@link Application.Builder#build()} is called.
* Before that the application is not built and no resources are claimed.
* </p>
* <p>
* Application IDs are unique. If an application ID is already allocated it
* cannot be allocated a second time. The second call to {@link Application.Builder#build()} will fail.
* However this application ID only allocated once the call to {@link Application.Builder#build()}
* succeeded.
* </p>
*
* @param applicationId
* The ID of the application to create
* @return the new {@link Application.Builder} instance
*/
public Application.Builder buildApplication(String applicationId);
}
53 changes: 53 additions & 0 deletions client/gateway/api/src/main/java/org/eclipse/kapua/client/gateway/Credentials.java
View file
Open in desktop
@@ -0,0 +1,53 @@
/*******************************************************************************
* Copyright (c) 2017 Red Hat Inc and others.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Red Hat Inc - initial API and implementation
*******************************************************************************/
package org.eclipse.kapua.client.gateway;

public final class Credentials {

private Credentials() {
}

public static class UserAndPassword {

private final String username;
private final char[] password;

private UserAndPassword(final String username, final char[] password) {
this.username = username;
this.password = password;
}

public String getUsername() {
return username;
}

public char[] getPassword() {
return password;
}

public String getPasswordAsString() {
if (password == null) {
return null;
}

return String.valueOf(password);
}
}

public static UserAndPassword userAndPassword(final String username, final String password) {
return new UserAndPassword(username, password != null ? password.toCharArray() : null);
}

public static UserAndPassword userAndPassword(final String username, final char[] password) {
return new UserAndPassword(username, password);
}
}
53 changes: 53 additions & 0 deletions client/gateway/api/src/main/java/org/eclipse/kapua/client/gateway/Data.java
View file
Open in desktop
@@ -0,0 +1,53 @@
/*******************************************************************************
* Copyright (c) 2017 Red Hat Inc and others.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Red Hat Inc - initial API and implementation
*******************************************************************************/
package org.eclipse.kapua.client.gateway;

/**
* An interface for control data
* <p>
* An instance of this is bound to a topic and can be looked up by a call
* to {@link Application#data(Topic)}.
* </p>
*/
public interface Data extends Sender<Exception> {

/**
* Receive messages on this data topic
* <p>
* Subscriptions will automatically be re-established after a connection loss.
* </p>
*
* @param handler
* the handler which should process received messages
* @throws Exception
* if anything goes wrong on the subscription process
*/
public default void subscribe(final MessageHandler handler) throws Exception {
subscribe(handler, Errors::ignore);
}

/**
* Receive messages and handle reception errors on this data topic
* <p>
* Subscriptions will automatically be re-established after a connection loss.
* </p>
*
* @param handler
* the handler which should process received messages
* @param errorHandler
* the handler which should process received messages which got received
* but could not be properly parsed
* @throws Exception
* if anything goes wrong on the subscription process
*/
public void subscribe(MessageHandler handler, ErrorHandler<? extends Throwable> errorHandler) throws Exception;
}
20 changes: 20 additions & 0 deletions client/gateway/api/src/main/java/org/eclipse/kapua/client/gateway/ErrorHandler.java
View file
Open in desktop
@@ -0,0 +1,20 @@
/*******************************************************************************
* Copyright (c) 2017 Red Hat Inc and others.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Red Hat Inc - initial API and implementation
*******************************************************************************/
package org.eclipse.kapua.client.gateway;

import java.util.Optional;

@FunctionalInterface
public interface ErrorHandler<X extends Throwable> {

public void handleError(Throwable e, Optional<Payload> payload) throws X;
}