[DE-765] architectural tests (#538)

* v7.5.0-SNAPSHOT

* archTest: InternalsTest

* archTest: annotated API classes

* archTest: annotated API methods and parameters

* archTest: annotated API constructors

* archTest: generic types

* archTest: annotated API with generic types

Author: rashtao

core/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>com.arangodb</groupId>
         <artifactId>arangodb-java-driver-parent</artifactId>
-        <version>7.4.0</version>
+        <version>7.5.0-SNAPSHOT</version>
     </parent>
 
     <name>core</name>

core/src/main/java/com/arangodb/ArangoDB.java

@@ -20,6 +20,7 @@
 
 package com.arangodb;
 
+import com.arangodb.arch.UnstableApi;
 import com.arangodb.config.ArangoConfigProperties;
 import com.arangodb.config.HostDescription;
 import com.arangodb.entity.*;
@@ -626,6 +627,7 @@ public Builder asyncExecutor(final Executor executor) {
             return this;
         }
 
+        @UnstableApi
         protected ProtocolProvider protocolProvider(Protocol protocol) {
             ServiceLoader<ProtocolProvider> loader = ServiceLoader.load(ProtocolProvider.class);
             for (ProtocolProvider p : loader) {
@@ -637,7 +639,8 @@ protected ProtocolProvider protocolProvider(Protocol protocol) {
             throw new ArangoDBException("No ProtocolProvider found for protocol: " + protocol);
         }
 
-        protected HostHandler createHostHandler(final HostResolver hostResolver) {
+        @UnstableApi
+        protected HostHandler createHostHandler(@UnstableApi final HostResolver hostResolver) {
 
             final HostHandler hostHandler;
 
@@ -664,7 +667,8 @@ protected HostHandler createHostHandler(final HostResolver hostResolver) {
             return new DirtyReadHostHandler(hostHandler, new RoundRobinHostHandler(hostResolver));
         }
 
-        protected HostResolver createHostResolver(final Collection<Host> hosts, final ConnectionFactory connectionFactory) {
+        @UnstableApi
+        protected HostResolver createHostResolver(@UnstableApi final Collection<Host> hosts, @UnstableApi final ConnectionFactory connectionFactory) {
             Boolean acquireHostList = config.getAcquireHostList();
             if (acquireHostList != null && acquireHostList) {
                 LOG.debug("acquireHostList -> Use ExtendedHostResolver");
@@ -676,7 +680,8 @@ protected HostResolver createHostResolver(final Collection<Host> hosts, final Co
             }
         }
 
-        protected Collection<Host> createHostList(final ConnectionFactory connectionFactory) {
+        @UnstableApi
+        protected Collection<Host> createHostList(@UnstableApi final ConnectionFactory connectionFactory) {
             final Collection<Host> hostList = new ArrayList<>();
             for (final HostDescription host : config.getHosts()) {
                 hostList.add(HostUtils.createHost(host, config, connectionFactory));

core/src/main/java/com/arangodb/ArangoSerdeAccessor.java

@@ -20,6 +20,7 @@
 
 package com.arangodb;
 
+import com.arangodb.arch.UnstableApi;
 import com.arangodb.internal.serde.InternalSerde;
 
 import javax.annotation.concurrent.ThreadSafe;
@@ -35,6 +36,7 @@ public interface ArangoSerdeAccessor {
      *
      * @return ArangoSerde
      */
+    @UnstableApi
     InternalSerde getSerde();
 
 }

core/src/main/java/com/arangodb/arch/NoRawTypesInspection.java

@@ -0,0 +1,15 @@
+package com.arangodb.arch;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Skip invoking {@code JavaType#getAllInvolvedRawTypes()} on the target class during arch tests.
+ * Prevents StackOverflowError caused by <a href="https://github.com/TNG/ArchUnit/issues/1237">this</a>.
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.TYPE)
+public @interface NoRawTypesInspection {
+}

core/src/main/java/com/arangodb/arch/UnstableApi.java

@@ -0,0 +1,22 @@
+package com.arangodb.arch;
+
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates a public API that has references to internal classes and that should change in the next major release.
+ * Referenced internal classes are annotated with {@link UsedInApi}.
+ * Architectural tests consider these annotation to tolerate referencing annotated elements.
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target({
+        ElementType.TYPE,
+        ElementType.METHOD,
+        ElementType.PARAMETER,
+        ElementType.FIELD
+})
+public @interface UnstableApi {
+}

core/src/main/java/com/arangodb/arch/UsedInApi.java

@@ -0,0 +1,18 @@
+package com.arangodb.arch;
+
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates an internal class referenced in public API, which should be therefore considered part of the public API.
+ * The annotated class and/or the referencing public API element should change in the next major release.
+ * Referencing element is annotated with {@link UnstableApi}.
+ * Architectural tests consider these annotation to tolerate referenced annotated elements.
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.TYPE)
+public @interface UsedInApi {
+}

core/src/main/java/com/arangodb/internal/InternalRequest.java

@@ -20,6 +20,8 @@
 
 package com.arangodb.internal;
 
+import com.arangodb.arch.UsedInApi;
+
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Locale;
@@ -28,6 +30,7 @@
 /**
  * @author Mark Vollmary
  */
+@UsedInApi
 public class InternalRequest {
 
     private final String dbName;

core/src/main/java/com/arangodb/internal/InternalResponse.java

@@ -20,6 +20,8 @@
 
 package com.arangodb.internal;
 
+import com.arangodb.arch.UsedInApi;
+
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Locale;
@@ -28,6 +30,7 @@
 /**
  * @author Mark Vollmary
  */
+@UsedInApi
 public class InternalResponse {
 
     private int version = 1;

core/src/main/java/com/arangodb/internal/config/ArangoConfig.java

@@ -3,6 +3,7 @@
 import com.arangodb.ArangoDBException;
 import com.arangodb.ContentType;
 import com.arangodb.Protocol;
+import com.arangodb.arch.UsedInApi;
 import com.arangodb.config.ArangoConfigProperties;
 import com.arangodb.config.HostDescription;
 import com.arangodb.entity.LoadBalancingStrategy;
@@ -21,6 +22,7 @@
 import java.util.concurrent.Executor;
 import java.util.stream.Collectors;
 
+@UsedInApi
 public class ArangoConfig {
     private final List<HostDescription> hosts = new ArrayList<>();
     private Protocol protocol;

core/src/main/java/com/arangodb/internal/net/Communication.java

@@ -1,6 +1,7 @@
 package com.arangodb.internal.net;
 
 import com.arangodb.ArangoDBException;
+import com.arangodb.arch.UsedInApi;
 import com.arangodb.config.HostDescription;
 import com.arangodb.internal.InternalRequest;
 import com.arangodb.internal.InternalResponse;
@@ -22,6 +23,7 @@
 import java.util.concurrent.TimeoutException;
 import java.util.concurrent.atomic.AtomicLong;
 
+@UsedInApi
 public abstract class Communication implements Closeable {
     private static final Logger LOGGER = LoggerFactory.getLogger(Communication.class);
     protected final HostHandler hostHandler;

core/src/main/java/com/arangodb/internal/net/CommunicationProtocol.java

@@ -21,6 +21,7 @@
 package com.arangodb.internal.net;
 
 import com.arangodb.ArangoDBException;
+import com.arangodb.arch.UsedInApi;
 import com.arangodb.internal.InternalRequest;
 import com.arangodb.internal.InternalResponse;
 
@@ -31,6 +32,7 @@
 /**
  * @author Mark Vollmary
  */
+@UsedInApi
 public interface CommunicationProtocol extends Closeable {
 
     default InternalResponse execute(final InternalRequest request, final HostHandle hostHandle) {

core/src/main/java/com/arangodb/internal/net/Connection.java

@@ -20,6 +20,7 @@
 
 package com.arangodb.internal.net;
 
+import com.arangodb.arch.UsedInApi;
 import com.arangodb.internal.InternalRequest;
 import com.arangodb.internal.InternalResponse;
 
@@ -29,6 +30,7 @@
 /**
  * @author Mark Vollmary
  */
+@UsedInApi
 public interface Connection extends Closeable {
     void setJwt(String jwt);
 

core/src/main/java/com/arangodb/internal/net/ConnectionFactory.java

@@ -20,12 +20,14 @@
 
 package com.arangodb.internal.net;
 
+import com.arangodb.arch.UsedInApi;
 import com.arangodb.config.HostDescription;
 import com.arangodb.internal.config.ArangoConfig;
 
 /**
  * @author Mark Vollmary
  */
+@UsedInApi
 public interface ConnectionFactory {
     Connection create(ArangoConfig config, HostDescription host);
 }

core/src/main/java/com/arangodb/internal/net/Host.java

@@ -20,13 +20,15 @@
 
 package com.arangodb.internal.net;
 
+import com.arangodb.arch.UsedInApi;
 import com.arangodb.config.HostDescription;
 
 import java.io.IOException;
 
 /**
  * @author Mark Vollmary
  */
+@UsedInApi
 public interface Host {
 
     HostDescription getDescription();

core/src/main/java/com/arangodb/internal/net/HostHandle.java

@@ -20,11 +20,13 @@
 
 package com.arangodb.internal.net;
 
+import com.arangodb.arch.UsedInApi;
 import com.arangodb.config.HostDescription;
 
 /**
  * @author Mark Vollmary
  */
+@UsedInApi
 public class HostHandle {
 
     private HostDescription host;

core/src/main/java/com/arangodb/internal/net/HostHandler.java

@@ -20,13 +20,15 @@
 
 package com.arangodb.internal.net;
 
+import com.arangodb.arch.UsedInApi;
 import com.arangodb.config.HostDescription;
 
 import java.io.IOException;
 
 /**
  * @author Mark Vollmary
  */
+@UsedInApi
 public interface HostHandler {
 
     Host get(HostHandle hostHandle, AccessType accessType);

core/src/main/java/com/arangodb/internal/net/HostResolver.java

@@ -20,12 +20,14 @@
 
 package com.arangodb.internal.net;
 
+import com.arangodb.arch.UsedInApi;
 import com.arangodb.internal.ArangoExecutorSync;
 import com.arangodb.internal.serde.InternalSerde;
 
 /**
  * @author Mark Vollmary
  */
+@UsedInApi
 public interface HostResolver {
 
     default void init(ArangoExecutorSync executorSync, InternalSerde arangoSerialization) {

core/src/main/java/com/arangodb/internal/net/ProtocolProvider.java

@@ -2,9 +2,11 @@
 
 
 import com.arangodb.Protocol;
+import com.arangodb.arch.UsedInApi;
 import com.arangodb.internal.config.ArangoConfig;
 import com.fasterxml.jackson.databind.Module;
 
+@UsedInApi
 public interface ProtocolProvider {
 
     boolean supportsProtocol(Protocol protocol);

core/src/main/java/com/arangodb/internal/serde/InternalSerde.java

@@ -1,11 +1,13 @@
 package com.arangodb.internal.serde;
 
+import com.arangodb.arch.UsedInApi;
 import com.arangodb.serde.ArangoSerde;
 import com.arangodb.ContentType;
 import com.fasterxml.jackson.databind.JsonNode;
 
 import java.lang.reflect.Type;
 
+@UsedInApi
 public interface InternalSerde extends ArangoSerde {
 
     /**

core/src/main/java/com/arangodb/model/IndexOptions.java

@@ -20,11 +20,14 @@
 
 package com.arangodb.model;
 
+import com.arangodb.arch.NoRawTypesInspection;
+
 /**
  * @author Heiko Kernbach
  * <p>
  * This final class is used for all index similarities
  */
+@NoRawTypesInspection
 public abstract class IndexOptions<T extends IndexOptions<T>> {
 
     private Boolean inBackground;

driver/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <artifactId>arangodb-java-driver-parent</artifactId>
         <groupId>com.arangodb</groupId>
-        <version>7.4.0</version>
+        <version>7.5.0-SNAPSHOT</version>
     </parent>
 
     <name>arangodb-java-driver</name>
@@ -194,6 +194,10 @@
             <version>2.13.3</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>com.tngtech.archunit</groupId>
+            <artifactId>archunit-junit5</artifactId>
+        </dependency>
     </dependencies>
 
 </project>