Pull Request for v10.0 tools release

bindings-generator/pom.xml

@@ -11,7 +11,7 @@
     <parent>
         <groupId>com.vmware.vcloud</groupId>
         <artifactId>vcd-api-tooling-parent</artifactId>
-        <version>9.7</version>
+        <version>10.0.0</version>
     </parent>
     <name>${project.artifactId} :: Bindings generation utility</name>
     <description>Provides custom API bindings generation beyond what can be accomplished with xjc and OpenAPI</description>

pom.xml

@@ -8,7 +8,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.vmware.vcloud</groupId>
   <artifactId>vcd-api-tooling-parent</artifactId>
-  <version>9.7</version>
+  <version>10.0.0</version>
   <packaging>pom</packaging>
   <name>${project.artifactId} :: vCloud Director REST API tooling parent</name>
   <description>Parent project housing tools and utilities to process vCloud Director APIs and build bindings</description>

vcd-bindings-maven-plugin/pom.xml

@@ -12,7 +12,7 @@
     <parent>
         <groupId>com.vmware.vcloud</groupId>
         <artifactId>vcd-api-tooling-parent</artifactId>
-        <version>9.7</version>
+        <version>10.0.0</version>
     </parent>
     <name>${project.artifactId} :: Maven plugin wrapper for bindings generation utility</name>
 

vcd-xjc-plugins/pom.xml

@@ -10,7 +10,7 @@
   <parent>
     <groupId>com.vmware.vcloud</groupId>
     <artifactId>vcd-api-tooling-parent</artifactId>
-    <version>9.7</version>
+    <version>10.0.0</version>
   </parent>
   <packaging>jar</packaging>
   <name>${project.artifactId} :: Custom plugins for XML to Java Compilation</name>
@@ -37,4 +37,16 @@
    </dependency>
 
   </dependencies>
+  <build>
+    <plugins>
+      <plugin>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <configuration>
+          <encoding>utf8</encoding>
+          <source>1.8</source>
+          <target>1.8</target>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
 </project>

vcd-xjc-plugins/src/main/java/com/vmware/vcloud/api/annotation/ContentType.java

@@ -4,7 +4,7 @@
  * #%L
  * vcd-xjc-plugins :: Custom plugins for XML to Java Compilation
  * %%
- * Copyright (C) 2018 VMware, Inc.
+ * Copyright (C) 2018 - 2021 VMware, Inc.
  * %%
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are met:
@@ -45,3 +45,4 @@
 public @interface ContentType {
     String value();
 }
+

vcd-xjc-plugins/src/main/java/com/vmware/vcloud/api/annotation/MultiSite.java

@@ -0,0 +1,80 @@
+package com.vmware.vcloud.api.annotation;
+
+/*-
+ * #%L
+ * vcd-xjc-plugins :: Custom plugins for XML to Java Compilation
+ * %%
+ * Copyright (C) 2018 - 2021 VMware, Inc.
+ * %%
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ * #L%
+ */
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import javax.xml.bind.JAXBElement;
+
+import com.vmware.vcloud.api.rest.version.ApiVersion;
+
+
+/**
+ * Indicates that a handler method can handle multi-site requests. A list of collection field names
+ * to be merged in the result body can be optionally specified. A custom response builder class can
+ * also be optionallyspecified to handle aggregation of the federated responses. If neither is
+ * specified, default aggregation implementation will be applied to the results.
+ */
+@Inherited
+@Target({ ElementType.TYPE, ElementType.METHOD })
+@Retention(RetentionPolicy.RUNTIME)
+public @interface MultiSite {
+
+    /**
+     * Specifies the list of collection names in a {@link JAXBElement} type that should be merged to
+     * create a multi-site response. i.e. the contents of independent response objects from multiple
+     * associated Org endpoints will be merged into a single collection in the response object
+     */
+    String[] mergeCollections() default {};
+
+    /**
+     * Specifies a custom class to use to build a multi-site response object. If none specified, a
+     * default multi-site response builder will be used to construct a multi-site response for the
+     * request. Any mrgeCollections value is ignored if a custom response builder is specified
+     */
+    Class<?> customResponseBuilder() default Object.class;
+
+    /**
+     * Specifies an {@link ApiVersion.Alias} to add support for multi-site request fanout. If none
+     * specified, a default {@code ApiVersion.Alias.MULTI_SITE} is used
+     */
+    ApiVersion.Alias addedIn() default ApiVersion.Alias.MULTI_SITE;
+
+    /**
+     * Specifies an {@link ApiVersion.Alias} to remove support for multi-site request fanout. If
+     * none specified, a default {@code ApiVersion.Alias.FUTURE} is used
+     */
+    ApiVersion.Alias removedIn() default ApiVersion.Alias.FUTURE;
+}
+

vcd-xjc-plugins/src/main/java/com/vmware/vcloud/api/annotation/Restricted.java

@@ -0,0 +1,47 @@
+package com.vmware.vcloud.api.annotation;
+
+/*-
+ * #%L
+ * vcd-xjc-plugins :: Custom plugins for XML to Java Compilation
+ * %%
+ * Copyright (C) 2018 - 2021 VMware, Inc.
+ * %%
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ * #L%
+ */
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation denotes that the annotated field is potentially restricted. Before writing out or
+ * reading in this field, the API framework should determine if the caller is allowed to see/use the
+ * field.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.FIELD })
+public @interface Restricted {
+
+}
+

vcd-xjc-plugins/src/main/java/com/vmware/vcloud/api/annotation/Supported.java

@@ -4,7 +4,7 @@
  * #%L
  * vcd-xjc-plugins :: Custom plugins for XML to Java Compilation
  * %%
- * Copyright (C) 2018 VMware, Inc.
+ * Copyright (C) 2018 - 2021 VMware, Inc.
  * %%
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are met:
@@ -36,28 +36,27 @@
 
 /**
  * This annotation denotes when the specific feature was introduced to the
- * REST-API and if and when it was removed. <p>
- *
- * A feature is present starting from {@link #addedIn()} version inclusive, to
- * {@link #removedIn()} exclusive. <p>
- *
- * This annotation is added automatically to the JAXB generated classes.
+ * REST-API and if and when it was removed. This annotation is added
+ * automatically to the JAXB generated classes.
+ * <p>
+ * The feature is present starting from {@link #addedIn()} version inclusive, to
+ * {@link #removedIn()} exclusive.
+ * </p>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.FIELD, ElementType.METHOD, ElementType.TYPE })
 public @interface Supported {
 
+    public static final String VCLOUD_LEGACY_FILTER_PARAM = "vcloud_legacy";
+
     /**
-     * Version in which the feature was added, inclusive.
-     * 
-     * @return a version string
+     * Version in which the feature was added.
      */
     String addedIn();
 
     /**
-     * Version in which the feature was removed, exclusive.
-     * 
-     * @return a version string
+     * Version in which the feature was removed.
      */
     String removedIn() default "";
 }
+

vcd-xjc-plugins/src/main/java/com/vmware/vcloud/api/enums/EnumValidator.java

@@ -49,3 +49,4 @@ public interface EnumValidator<T extends Supported> extends Serializable {
      */
     void validate(String key, T value);
 }
+

vcd-xjc-plugins/src/main/java/com/vmware/vcloud/api/enums/NameVersionHolder.java

@@ -93,3 +93,4 @@ protected T validateValue(String key, T value) {
         return value;
     }
 }
+

vcd-xjc-plugins/src/main/java/com/vmware/vcloud/api/http/converters/JAXBElementConverter.java

@@ -0,0 +1,138 @@
+package com.vmware.vcloud.api.http.converters;
+
+/*-
+ * #%L
+ * vcd-xjc-plugins :: Custom plugins for XML to Java Compilation
+ * %%
+ * Copyright (C) 2018 - 2021 VMware, Inc.
+ * %%
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ * #L%
+ */
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
+
+import javax.xml.bind.JAXBElement;
+
+
+/**
+ * Converts an xsd-generated type into a {@link JAXBElement} wrapped representation
+ */
+public class JAXBElementConverter {
+
+    private static class ObjectFactoryInvocation {
+        final Object objectFactory;
+        final Method factoryMethod;
+
+        ObjectFactoryInvocation(Object objectFactory, Method factoryMethod) {
+            this.objectFactory = objectFactory;
+            this.factoryMethod = factoryMethod;
+        }
+
+        public JAXBElement<?> convert(Object value) throws IllegalAccessException, IllegalArgumentException, InvocationTargetException {
+            return (JAXBElement<?>) factoryMethod.invoke(objectFactory, value);
+        }
+    }
+
+
+    private final List<Object> objectFactories;
+
+    private static final ConcurrentMap<Class<?>, ObjectFactoryInvocation> jaxbFactoryMethods =
+            new ConcurrentHashMap<>();
+
+    public JAXBElementConverter(final List<Object> objectFactories) {
+        this.objectFactories = new ArrayList<>(objectFactories);
+    }
+
+    /**
+     * Locates the factory method from among the {@code ObjectFactory}s this instance was seeded
+     * with and converts the payload into its {@link JAXBElement} wrapped representation
+     *
+     * @param value
+     *            xsd-generated type object to be wrapped within a {@link JAXBElement}
+     * @return {@link JAXBElement} wrapped representation
+     *
+     * @throws IllegalAccessException
+     *             if there was an error invoking the factory method.
+     * @throws IllegalArgumentException
+     *             if factory method to rejected the argument.
+     * @throws NullPointerException
+     *             They payload to be converted has no applicable factory method to effect the
+     *             conversion.
+     * @throws InvocationTargetException
+     *             if there was an error invoking the factory method.
+     */
+    public JAXBElement<?> convertToJAXBElement(Object value) throws IllegalAccessException,
+                                                             IllegalArgumentException,
+                                                             NullPointerException,
+                                                             InvocationTargetException {
+
+        final ObjectFactoryInvocation jaxbConverter = getJAXBFactoryMethodInfo(value.getClass());
+        final JAXBElement<?> result = jaxbConverter.convert(value);
+        return result;
+    }
+
+    /**
+     * For a payload type locate the {@code ObjectFactory} and the {@link Method} on that factory
+     * that will effect the conversion
+     * <P>
+     * The pair is wrapped in an {@link ObjectFactoryInvocation} object and cached for quicker
+     * lookups in the future
+     *
+     * @param elementCls
+     *            - xsd-generated type's {@link Class}
+     *
+     * @return {@link ObjectFactoryInvocation} whose {@link ObjectFactoryInvocation#convert(Object)
+     *         convert} method can be invoked to get the {@link JAXBElement}
+     */
+    private  ObjectFactoryInvocation getJAXBFactoryMethodInfo(Class<?> elementCls) {
+        return jaxbFactoryMethods.computeIfAbsent(elementCls, this::getConverter);
+    }
+
+    private  ObjectFactoryInvocation getConverter(Class<?> elementCls) {
+        for (Object factory : objectFactories) {
+            Method[] methods = factory.getClass().getMethods();
+            for (Method m : methods) {
+                Class<?>[] pTypes = m.getParameterTypes();
+                Class<?> pType = null;
+                if (pTypes != null && pTypes.length == 1) {
+                    pType = pTypes[0];
+                } else {
+                    continue;
+                }
+
+                Class<?> type = m.getReturnType();
+                if (elementCls.equals(pType) && JAXBElement.class.isAssignableFrom(type)) {
+                    return new ObjectFactoryInvocation(factory, m);
+                }
+            }
+        }
+
+        return null;
+    }
+}
+

vcd-xjc-plugins/src/main/java/com/vmware/vcloud/api/http/converters/JAXBElementMixIn.java

@@ -51,4 +51,3 @@ public abstract class JAXBElementMixIn<T> {
     public abstract Object getValue();
 }
 
-