bug5311: added new bundle com.sap.sailing.server.gateway.interfaces as Java facade for remote sailing server REST API

2026-09-21 21:25:38 +00:00 · 2021-08-18 17:40:52 +02:00
parent 77c44d520e
commit 2566987354
14 changed files with 170 additions and 1 deletions
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.8"/>
+	<classpathentry kind="con" path="org.eclipse.pde.core.requiredPlugins"/>
+	<classpathentry kind="src" path="src"/>
+	<classpathentry kind="output" path="bin"/>
+</classpath>
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>com.sap.sailing.server.gateway.interfaces</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.jdt.core.javabuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.pde.ManifestBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.pde.SchemaBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.pde.PluginNature</nature>
+		<nature>org.eclipse.jdt.core.javanature</nature>
+	</natures>
+</projectDescription>
@@ -0,0 +1,8 @@
+eclipse.preferences.version=1
+org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled
+org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.8
+org.eclipse.jdt.core.compiler.compliance=1.8
+org.eclipse.jdt.core.compiler.problem.assertIdentifier=error
+org.eclipse.jdt.core.compiler.problem.enumIdentifier=error
+org.eclipse.jdt.core.compiler.release=disabled
+org.eclipse.jdt.core.compiler.source=1.8
@@ -0,0 +1,3 @@
+eclipse.preferences.version=1
+pluginProject.extensions=false
+resolve.requirebundle=false
@@ -0,0 +1,8 @@
+Manifest-Version: 1.0
+Bundle-ManifestVersion: 2
+Bundle-Name: Interface
+Bundle-SymbolicName: com.sap.sailing.server.gateway.interfaces
+Bundle-Version: 1.0.0.qualifier
+Bundle-Vendor: SAP
+Automatic-Module-Name: com.sap.sailing.server.gateway.interface
+Bundle-RequiredExecutionEnvironment: JavaSE-1.8
@@ -0,0 +1,4 @@
+source.. = src/
+output.. = bin/
+bin.includes = META-INF/,\
+               .
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <artifactId>root</artifactId>
+    <groupId>com.sap.sailing</groupId>
+    <version>1.0.0-SNAPSHOT</version>
+  </parent>
+  <artifactId>com.sap.sailing.server.gateway.interfaces</artifactId>
+  <packaging>eclipse-plugin</packaging>
+</project>
@@ -0,0 +1,5 @@
+package com.sap.sailing.server.gateway.interfaces;
+
+public interface CompareServersResult {
+
+}
@@ -0,0 +1,5 @@
+package com.sap.sailing.server.gateway.interfaces;
+
+public interface MasterDataImportResult {
+
+}
@@ -0,0 +1,27 @@
+package com.sap.sailing.server.gateway.interfaces;
+
+import java.util.Optional;
+import java.util.Set;
+import java.util.UUID;
+
+/**
+ * Represents a remote instance of a server process running the Sailing Analytics and exposes various methods as a
+ * convenient Java API which are implemented using the remote server's REST API. In short, this is a Java facade for a
+ * REST API.
+ * <p>
+ * 
+ * Objects of this type manage authentication information required for executing its methods as part of their immutable
+ * state, therefore at object construction time. Authentication information may be provided in the form of
+ * username/password which can then be used to obtain a bearer token for remote access. Or the bearer token for the
+ * server can be provided explicitly. Or, as the default, the constructor checks whether running in the scope of
+ * an authenticated session and then uses that session user's bearer token, assuming that the server to be represented
+ * by this object shares its security service with the server where this object is constructed.<p>
+ */
+public interface SailingServer {
+    Iterable<UUID> getLeaderboardGroupIds();
+    Iterable<UUID> getEventIds();
+    MasterDataImportResult importMasterData(SailingServer from, Iterable<UUID> leaderboardGroupIds);
+    CompareServersResult compareServers(SailingServer a, Optional<SailingServer> b);
+    void addRemoteServerReference(SailingServer referencedServer, Optional<Set<UUID>> eventIds);
+    void removeRemoteServerReference(SailingServer referencedServer, Optional<Set<UUID>> eventIds);
+}
@@ -0,0 +1,45 @@
+package com.sap.sailing.server.gateway.interfaces;
+
+import java.net.URL;
+
+/**
+ * A factory service that obtains {@link SailingServer} instances which represent (usually remote) server processes,
+ * identified by a {@link URL} that is used as the base to construct the REST API URLs, plus the authentication
+ * information necessary to authenticate calls.
+ * <p>
+ * 
+ * Using {@link #getSailingServer(URL)} may be used to try authentication with the bearer token of the current local
+ * user session, if any. If no such session exists, the {@link SailingServer} returned will make its REST calls without
+ * any form of authentication, restricting the services that can be invoked to those that are publicly accessible.
+ * <p>
+ * 
+ * The "base URL" needs to contain protocol, host and port specification and an empty path or only "/" as path.
+ * <p>
+ * 
+ * The intended use is through the OSGi service registry: clients are expected to discover and track an implementation
+ * of this interface and then use that to obtain an anonymous or authenticated {@link SailingServer} instance.
+ * 
+ * @author Axel Uhl (D043530)
+ *
+ */
+public interface SailingServerFactory {
+    /**
+     * Looks for a local authenticated security session; if found, that session's bearer token will be used to
+     * authenticate calls to the resulting {@link SailingServer}, assuming it shares a security service with
+     * the local server that executes this method. If no local authenticated session is found, calls to the
+     * {@link SailingServer} returned will be anonymous and hence be restricted to those publicly available.
+     */
+    SailingServer getSailingServer(URL baseUrl);
+    
+    /**
+     * Explicitly authenticates calls to the resulting {@link SailingServer} using the {@code bearerToken}
+     * provided.
+     */
+    SailingServer getSailingServer(URL baseUrl, String bearerToken);
+    
+    /**
+     * Authenticates calls to the resulting {@link SailingServer} by obtaining a bearer token from that server
+     * through basic authentication with the {@code username} and {@code password} provided.
+     */
+    SailingServer getSailingServer(URL baseUrl, String username, String password);
+}
@@ -0,0 +1,15 @@
+/**
+ * Java interfaces for functionality from {@code com.sap.sailing.server.gateway}, particularly for accessing
+ * functionality on remote server process instances exposed through the REST API implemented by the gateway
+ * bundle.<p>
+ * 
+ * The gateway bundle can register service implementations using the interfaces exposed by this bundle here, so
+ * that when the gateway bundle needs a refresh / reload, services specified in this bundle can still be discovered
+ * and tracked and be bound and resolved again, e.g., after a restart of the gateway bundle.<p>
+ * 
+ * Furthermore, other bundles who would like to use these services won't need a dependency on the
+ * {@code com.sap.sailing.server.gateway} bundle.
+ * 
+ * @author Axel Uhl (d043530)
+ */
+package com.sap.sailing.server.gateway.interfaces;