Merge branch 'REL1_6_STABLE'

Author: jcflack

.travis.yml

@@ -250,6 +250,22 @@ script: |
         // state 9: must be end of input
         (o,p,q) -> null == o
       );
+
+      /*
+       * Also confirm that the generated undeploy actions work.
+       */
+      succeeding &= stateMachine(
+        "remove jar void result",
+        null,
+
+        q(c, "SELECT sqlj.remove_jar('examples', true)")
+        .flatMap(Node::semiFlattenDiagnostics)
+        .peek(Node::peek),
+
+        (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
+        (o,p,q) -> isVoidResultSet(o, 1, 1) ? 3 : false,
+        (o,p,q) -> null == o
+      );
     }
   } catch ( Throwable t )
   {

appveyor.yml

@@ -188,6 +188,22 @@ test_script:
             // state 9: must be end of input
             (o,p,q) -> null == o
           );
+
+          /*
+           * Also confirm that the generated undeploy actions work.
+           */
+          succeeding &= stateMachine(
+            "remove jar void result",
+            null,
+
+            q(c, "SELECT sqlj.remove_jar('examples', true)")
+            .flatMap(Node::semiFlattenDiagnostics)
+            .peek(Node::peek),
+
+            (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
+            (o,p,q) -> isVoidResultSet(o, 1, 1) ? 3 : false,
+            (o,p,q) -> null == o
+          );
         }
       } catch ( Throwable t )
       {

pljava-api/src/main/java/org/postgresql/pljava/annotation/Aggregate.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015- Tada AB and other contributors, as listed below.
+ * Copyright (c) 2015-2020 Tada AB and other contributors, as listed below.
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the The BSD 3-Clause License
@@ -11,6 +11,7 @@
  */
 package org.postgresql.pljava.annotation;
 
+import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
@@ -64,7 +65,7 @@
  * be used in their {@code @Function} annotations and this annotation, to make
  * the order come out right.
  */
-@Target(ElementType.TYPE) @Retention(RetentionPolicy.CLASS)
+@Target(ElementType.TYPE) @Retention(RetentionPolicy.CLASS) @Documented
 public @interface BaseUDT
 {
 	/**

pljava-api/src/main/java/org/postgresql/pljava/annotation/BaseUDT.java

@@ -0,0 +1,143 @@
+/*
+ * Copyright (c) 2020 Tada AB and other contributors, as listed below.
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the The BSD 3-Clause License
+ * which accompanies this distribution, and is available at
+ * http://opensource.org/licenses/BSD-3-Clause
+ *
+ * Contributors:
+ *   Chapman Flack
+ */
+package org.postgresql.pljava.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Declares a PostgreSQL {@code CAST}.
+ *<p>
+ * May annotate a Java method (which should also carry a
+ * {@link Function @Function} annotation, making it a PostgreSQL function),
+ * or a class or interface (just to have a place to put it when not directly
+ * associated with a method).
+ *<p>
+ * If not applied to a method, must supply {@code path=} specifying
+ * {@code BINARY} or {@code INOUT}.
+ *<p>
+ * The source and target types must be specified with {@code from} and
+ * {@code to}, unless the annotation appears on a method, in which case these
+ * default to the first parameter and return types of the function,
+ * respectively.
+ *<p>
+ * The cast will, by default, have to be applied explicitly, unless
+ * {@code application=ASSIGNMENT} or {@code application=IMPLICIT} is given.
+ *
+ * @author Chapman Flack
+ */
+@Documented
+@Target({ElementType.METHOD, ElementType.TYPE})
+@Repeatable(Cast.Container.class)
+@Retention(RetentionPolicy.CLASS)
+public @interface Cast
+{
+	/**
+	 * When this cast can be applied: only in explicit form, when used in
+	 * assignment context, or implicitly whenever needed.
+	 */
+	enum Application { EXPLICIT, ASSIGNMENT, IMPLICIT };
+
+	/**
+	 * A known conversion path when a dedicated function is not supplied:
+	 * {@code BINARY} for two types that are known to have the same internal
+	 * representation, or {@code INOUT} to invoke the first type's text-output
+	 * function followed by the second type's text-input function.
+	 */
+	enum Path { BINARY, INOUT };
+
+	/**
+	 * The source type to be cast. Will default to the first parameter type of
+	 * the associated function, if known.
+	 *<p>
+	 * PostgreSQL will allow this type and the function's first parameter type
+	 * to differ, if there is an existing binary cast between them. That cannot
+	 * be checked at compile time, so a cast with a different type given here
+	 * might successfully compile but fail to deploy in PostgreSQL.
+	 */
+	String from() default "";
+
+	/**
+	 * The target type to cast to. Will default to the return type of
+	 * the associated function, if known.
+	 *<p>
+	 * PostgreSQL will allow this type and the function's return type
+	 * to differ, if there is an existing binary cast between them. That cannot
+	 * be checked at compile time, so a cast with a different type given here
+	 * might successfully compile but fail to deploy in PostgreSQL.
+	 */
+	String to() default "";
+
+	/**
+	 * A stock conversion path when a dedicated function is not supplied:
+	 * {@code BINARY} for two types that are known to have the same internal
+	 * representation, or {@code INOUT} to invoke the first type's text-output
+	 * function followed by the second type's text-input function.
+	 *<p>
+	 * To declare an {@code INOUT} cast, {@code with=INOUT} must appear
+	 * explicitly; the default value is treated as unspecified.
+	 */
+	Path path() default Path.INOUT;
+
+	/**
+	 * When this cast can be applied: only in explicit form, when used in
+	 * assignment context, or implicitly whenever needed.
+	 */
+	Application application() default Application.EXPLICIT;
+
+	/**
+	 * One or more arbitrary labels that will be considered 'provided' by the
+	 * object carrying this annotation. The deployment descriptor will be
+	 * generated in such an order that other objects that 'require' labels
+	 * 'provided' by this come later in the output for install actions, and
+	 * earlier for remove actions.
+	 */
+	String[] provides() default {};
+
+	/**
+	 * One or more arbitrary labels that will be considered 'required' by the
+	 * object carrying this annotation. The deployment descriptor will be
+	 * generated in such an order that other objects that 'provide' labels
+	 * 'required' by this come earlier in the output for install actions, and
+	 * later for remove actions.
+	 */
+	String[] requires() default {};
+
+	/**
+	 * The {@code <implementor name>} to be used around SQL code generated
+	 * for this cast. Defaults to {@code PostgreSQL}. Set explicitly to
+	 * {@code ""} to emit code not wrapped in an {@code <implementor block>}.
+	 */
+	String implementor() default "";
+
+	/**
+	 * A comment to be associated with the cast. If left to default, and the
+	 * annotated Java construct has a doc comment, its first sentence will be
+	 * used. If an empty string is explicitly given, no comment will be set.
+	 */
+	String comment() default "";
+
+	/**
+	 * @hidden container type allowing Cast to be repeatable.
+	 */
+	@Documented
+	@Target({ElementType.METHOD, ElementType.TYPE})
+	@Retention(RetentionPolicy.CLASS)
+	@interface Container
+	{
+		Cast[] value();
+	}
+}

pljava-api/src/main/java/org/postgresql/pljava/annotation/Cast.java

@@ -78,9 +78,27 @@ enum Parallel { UNSAFE, RESTRICTED, SAFE };
 	 * {@link org.postgresql.pljava.ResultSetProvider ResultSetProvider},
 	 * or can be used to specify the return type of any function if the
 	 * compiler hasn't inferred it correctly.
+	 *<p>
+	 * Only one of {@code type} or {@code out} may appear.
 	 */
 	String type() default "";
 
+	/**
+	 * The result column names and types of a composite-returning function.
+	 *<p>
+	 * This is for a function defining its own one-off composite type
+	 * (declared with {@code OUT} parameters). If the function returns some
+	 * composite type known to the catalog, simply use {@code type} and the name
+	 * of that type.
+	 *<p>
+	 * Each element is a name and a type specification, separated by whitespace.
+	 * An element that begins with whitespace declares an output column with no
+	 * name, only a type. The name is an ordinary SQL identifier; if it would
+	 * be quoted in SQL, naturally each double-quote must be represented as
+	 * {@code \"} in Java.
+	 */
+	String[] out() default {};
+
 	/**
 	 * The name of the function. This is optional. The default is
 	 * to use the name of the annotated method. 
@@ -173,7 +191,8 @@ enum Parallel { UNSAFE, RESTRICTED, SAFE };
 	String language() default "";
 
 	/** 
-	 * Whether the function is UNSAFE to use in any parallel query plan at all
+	 * Whether the function is <a id='parallel'>UNSAFE</a> to use in any
+	 * parallel query plan at all
 	 * (the default), or avoids all disqualifying operations and so is SAFE to
 	 * execute anywhere in a parallel plan, or, by avoiding <em>some</em> such
 	 * operations, may appear in parallel plans but RESTRICTED to execute only

pljava-api/src/main/java/org/postgresql/pljava/annotation/Function.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015- Tada AB and other contributors, as listed below.
+ * Copyright (c) 2015-2020 Tada AB and other contributors, as listed below.
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the The BSD 3-Clause License
@@ -11,6 +11,7 @@
  */
 package org.postgresql.pljava.annotation;
 
+import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
@@ -42,7 +43,7 @@
  * of the class being annotated, and found in {@link #schema schema} if
  * specified, or by following the search path) to the annotated class.
  */
-@Target(ElementType.TYPE) @Retention(RetentionPolicy.CLASS)
+@Target(ElementType.TYPE) @Retention(RetentionPolicy.CLASS) @Documented
 public @interface MappedUDT
 {
 	/**