Core: Simplify/improve View APIs

.palantir/revapi.yml

@@ -743,6 +743,37 @@ acceptedBreaks:
       new: "method java.util.List<org.apache.iceberg.UpdateRequirement> org.apache.iceberg.rest.requests.UpdateTableRequest::requirements()"
       justification: "Signature changed to an interface, but this is safe because\
         \ of type erasure and the original type is always returned"
+  "1.3.0":
+    org.apache.iceberg:iceberg-api:
+    - code: "java.class.removed"
+      old: "class org.apache.iceberg.view.ImmutableSQLViewRepresentation"
+      justification: "Moving from iceberg-api to iceberg-core"
+    - code: "java.class.removed"
+      old: "class org.apache.iceberg.view.ImmutableViewHistoryEntry"
+      justification: "Moving from iceberg-api to iceberg-core"
+    - code: "java.class.removed"
+      old: "class org.apache.iceberg.view.ImmutableViewVersion"
+      justification: "Moving from iceberg-api to iceberg-core"
+    - code: "java.class.removed"
+      old: "interface org.apache.iceberg.view.SQLViewRepresentation"
+      justification: "Moving from iceberg-api to iceberg-core"
+    - code: "java.method.numberOfParametersChanged"
+      old: "method org.apache.iceberg.view.ViewBuilder org.apache.iceberg.view.ViewBuilder::withQuery(java.lang.String)"
+      new: "method T org.apache.iceberg.view.VersionBuilder<T>::withQuery(java.lang.String,\
+        \ java.lang.String) @ org.apache.iceberg.view.ViewBuilder"
+      justification: "Acceptable break due to updating View APIs and the View Spec"
+    - code: "java.method.removed"
+      old: "method org.apache.iceberg.view.ViewBuilder org.apache.iceberg.view.ViewBuilder::withDialect(java.lang.String)"
+      justification: "Acceptable break due to updating View APIs and the View Spec"
+    - code: "java.method.removed"
+      old: "method org.apache.iceberg.view.ViewBuilder org.apache.iceberg.view.ViewBuilder::withFieldAliases(java.util.List<java.lang.String>)"
+      justification: "Acceptable break due to updating View APIs and the View Spec"
+    - code: "java.method.removed"
+      old: "method org.apache.iceberg.view.ViewBuilder org.apache.iceberg.view.ViewBuilder::withFieldComments(java.util.List<java.lang.String>)"
+      justification: "Acceptable break due to updating View APIs and the View Spec"
+    - code: "java.method.removed"
+      old: "method org.apache.iceberg.view.ViewBuilder org.apache.iceberg.view.ViewBuilder::withQueryColumnNames(java.util.List<java.lang.String>)"
+      justification: "Acceptable break due to updating View APIs and the View Spec"
   apache-iceberg-0.14.0:
     org.apache.iceberg:iceberg-api:
     - code: "java.class.defaultSerializationChanged"

api/src/main/java/org/apache/iceberg/view/ReplaceViewVersion.java

@@ -0,0 +1,32 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.iceberg.view;
+
+import org.apache.iceberg.PendingUpdate;
+
+/**
+ * API for replacing a view's version.
+ *
+ * <p>Apply returns the updated view version for validation.
+ *
+ * <p>When committing, these changes will be applied to the current view metadata. Commit conflicts
+ * will be resolved by applying the pending changes to the new view metadata.
+ */
+public interface ReplaceViewVersion
+    extends PendingUpdate<ViewVersion>, VersionBuilder<ReplaceViewVersion> {}

api/src/main/java/org/apache/iceberg/view/VersionBuilder.java

@@ -0,0 +1,57 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.iceberg.view;
+
+import org.apache.iceberg.Schema;
+import org.apache.iceberg.catalog.Namespace;
+
+public interface VersionBuilder<T> {
+  /**
+   * Set the view schema.
+   *
+   * @param schema The schema to use for this view version
+   * @return this for method chaining
+   */
+  T withSchema(Schema schema);
+
+  /**
+   * Add a view representation for the given dialect and the SQL to the view.
+   *
+   * @param dialect The dialect of the view representation
+   * @param sql The SQL of the view representation
+   * @return this for method chaining
+   */
+  T withQuery(String dialect, String sql);
+
+  /**
+   * Set the default catalog to use for the view.
+   *
+   * @param catalog The default catalog to use when the SQL does not contain a catalog
+   * @return this for method chaining
+   */
+  T withDefaultCatalog(String catalog);
+
+  /**
+   * Set the default namespace to use for the view.
+   *
+   * @param namespace The default namespace to use when the SQL does not contain a namespace
+   * @return this for method chaining
+   */
+  T withDefaultNamespace(Namespace namespace);
+}

api/src/main/java/org/apache/iceberg/view/View.java

@@ -83,4 +83,13 @@ public interface View {
    * @return a new {@link UpdateViewProperties}
    */
   UpdateViewProperties updateProperties();
+
+  /**
+   * Create a new {@link ReplaceViewVersion} to replace the view's current version.
+   *
+   * @return a new {@link ReplaceViewVersion}
+   */
+  default ReplaceViewVersion replaceVersion() {
+    throw new UnsupportedOperationException("Replacing a view's version is not supported");
+  }
 }

api/src/main/java/org/apache/iceberg/view/ViewBuilder.java

@@ -18,81 +18,15 @@
  */
 package org.apache.iceberg.view;
 
-import java.util.List;
 import java.util.Map;
-import org.apache.iceberg.Schema;
-import org.apache.iceberg.catalog.Namespace;
 import org.apache.iceberg.catalog.ViewCatalog;
 
 /**
  * A builder used to create or replace a SQL {@link View}.
  *
  * <p>Call {@link ViewCatalog#buildView} to create a new builder.
  */
-public interface ViewBuilder {
-  /**
-   * Set the view schema.
-   *
-   * @param schema view schema
-   * @return this for method chaining
-   */
-  ViewBuilder withSchema(Schema schema);
-
-  /**
-   * Set the view query.
-   *
-   * @param query view query
-   * @return this for method chaining
-   */
-  ViewBuilder withQuery(String query);
-
-  /**
-   * Set the view SQL dialect.
-   *
-   * @param dialect view SQL dialect
-   * @return this for method chaining
-   */
-  ViewBuilder withDialect(String dialect);
-
-  /**
-   * Set the view default catalog.
-   *
-   * @param defaultCatalog view default catalog
-   * @return this for method chaining
-   */
-  ViewBuilder withDefaultCatalog(String defaultCatalog);
-
-  /**
-   * Set the view default namespace.
-   *
-   * @param defaultNamespace view default namespace
-   * @return this for method chaining
-   */
-  ViewBuilder withDefaultNamespace(Namespace defaultNamespace);
-
-  /**
-   * Set the view query column names.
-   *
-   * @param queryColumnNames view query column names
-   * @return this for method chaining
-   */
-  ViewBuilder withQueryColumnNames(List<String> queryColumnNames);
-
-  /**
-   * Set the view field aliases.
-   *
-   * @param fieldAliases view field aliases
-   * @return this for method chaining
-   */
-  ViewBuilder withFieldAliases(List<String> fieldAliases);
-
-  /**
-   * Set the view field comments.
-   *
-   * @param fieldComments view field comments
-   * @return this for method chaining
-   */
-  ViewBuilder withFieldComments(List<String> fieldComments);
+public interface ViewBuilder extends VersionBuilder<ViewBuilder> {
 
   /**
    * Add key/value properties to the view.

api/src/main/java/org/apache/iceberg/view/ViewHistoryEntry.java

@@ -18,15 +18,12 @@
  */
 package org.apache.iceberg.view;
 
-import org.immutables.value.Value;
-
 /**
  * View history entry.
  *
  * <p>An entry contains a change to the view state. At the given timestamp, the current version was
  * set to the given version ID.
  */
-@Value.Immutable
 public interface ViewHistoryEntry {
   /** Return the timestamp in milliseconds of the change */
   long timestampMillis();

api/src/main/java/org/apache/iceberg/view/ViewVersion.java

@@ -20,8 +20,8 @@
 
 import java.util.List;
 import java.util.Map;
+import org.apache.iceberg.catalog.Namespace;
 import org.apache.iceberg.relocated.com.google.common.base.Preconditions;
-import org.immutables.value.Value;
 
 /**
  * A version of the view at a point in time.
@@ -30,7 +30,6 @@
  *
  * <p>Versions are created by view operations, like Create and Replace.
  */
-@Value.Immutable
 public interface ViewVersion {
 
   /** Return this version's id. Version ids are monotonically increasing */
@@ -66,15 +65,23 @@ public interface ViewVersion {
    *
    * @return the string operation which produced the view version
    */
-  @Value.Lazy
   default String operation() {
     return summary().get("operation");
   }
 
   /** The query output schema at version create time, without aliases */
   int schemaId();
 
-  @Value.Check
+  /** The default catalog when the view is created. */
+  default String defaultCatalog() {
+    return null;
+  }
+
+  /** The default namespace to use when the SQL does not contain a namespace. */
+  default Namespace defaultNamespace() {
+    return null;
+  }
+
   default void check() {
     Preconditions.checkArgument(
         summary().containsKey("operation"), "Invalid view version summary, missing operation");

core/src/main/java/org/apache/iceberg/view/BaseViewHistoryEntry.java

@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.iceberg.view;
+
+import org.immutables.value.Value;
+
+/**
+ * View history entry.
+ *
+ * <p>An entry contains a change to the view state. At the given timestamp, the current version was
+ * set to the given version ID.
+ */
+@Value.Immutable
+// https://github.com/immutables/immutables/issues/291 does not apply here because we're not adding
+// any Immutable-specific class to the classpath
+@SuppressWarnings("ImmutablesStyle")
+@Value.Style(typeImmutable = "ImmutableViewHistoryEntry")
+public interface BaseViewHistoryEntry extends ViewHistoryEntry {}

core/src/main/java/org/apache/iceberg/view/BaseViewVersion.java

@@ -0,0 +1,58 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.iceberg.view;
+
+import javax.annotation.Nullable;
+import org.apache.iceberg.catalog.Namespace;
+import org.immutables.value.Value;
+
+/**
+ * A version of the view at a point in time.
+ *
+ * <p>A version consists of a view metadata file.
+ *
+ * <p>Versions are created by view operations, like Create and Replace.
+ */
+@Value.Immutable
+// https://github.com/immutables/immutables/issues/291 does not apply here because we're not adding
+// any Immutable-specific class to the classpath
+@SuppressWarnings("ImmutablesStyle")
+@Value.Style(typeImmutable = "ImmutableViewVersion")
+public interface BaseViewVersion extends ViewVersion {
+
+  @Override
+  @Value.Lazy
+  default String operation() {
+    return summary().get("operation");
+  }
+
+  @Override
+  @Nullable
+  String defaultCatalog();
+
+  @Override
+  @Nullable
+  Namespace defaultNamespace();
+
+  @Override
+  @Value.Check
+  default void check() {
+    ViewVersion.super.check();
+  }
+}