Formalize job naming

Signed-off-by: Dominik Dębowczyk <dominik.debowczyk@getindata.com>

Author: ddebowczyk92

client/java/src/main/java/io/openlineage/client/job/Naming.java

@@ -0,0 +1,70 @@
+/*
+/* Copyright 2018-2025 contributors to the OpenLineage project
+/* SPDX-License-Identifier: Apache-2.0
+*/
+
+package io.openlineage.client.job;
+
+import javax.annotation.Nullable;
+import lombok.Builder;
+
+/**
+ * Utility class for constructing job names according to the OpenLineage job naming conventions.
+ *
+ * <p>Supported job types include:
+ *
+ * <ul>
+ *   <li>Spark: {@code {appName}.{command}.{table}}
+ * </ul>
+ */
+@SuppressWarnings("PMD.MissingStaticMethodInNonInstantiatableClass")
+public class Naming {
+
+  private Naming() {}
+
+  /** Interface representing a job name that can be resolved to a string. */
+  public interface JobName {
+    /**
+     * Returns the formatted job name.
+     *
+     * @return a string representing the job name.
+     */
+    String getName();
+  }
+
+  /** Represents a Spark job name using the format: {@code {appName}.{command}.{table}}. */
+  @Builder
+  public static class Spark implements JobName {
+    private final String appName;
+    private final String command;
+    private final String table;
+
+    /**
+     * Constructs a new {@link Spark} job name.
+     *
+     * @param appName the Spark application name; must be non-null and non-empty
+     * @param command the command or function being run; must be non-null and non-empty
+     * @param table the target table; must be non-null and non-empty
+     * @throws IllegalArgumentException if any argument is empty
+     * @throws NullPointerException if any argument is null
+     */
+    public Spark(String appName, @Nullable String command, @Nullable String table) {
+      if (appName.isEmpty()) {
+        throw new IllegalArgumentException("appName, command, and table must be non-empty");
+      }
+      this.appName = appName;
+      this.command = command;
+      this.table = table;
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @return the job name in the format: {@code {appName}.{command}.{table}}
+     */
+    @Override
+    public String getName() {
+      return appName + (command != null ? "." + command : "") + (table != null ? "." + table : "");
+    }
+  }
+}

client/java/src/test/java/io/openlineage/client/job/NamingTest.java

@@ -0,0 +1,38 @@
+/*
+/* Copyright 2018-2025 contributors to the OpenLineage project
+/* SPDX-License-Identifier: Apache-2.0
+*/
+
+package io.openlineage.client.job;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import org.junit.jupiter.api.Test;
+
+class NamingTest {
+
+  @Test
+  void testSparkJobName() {
+    Naming.Spark spark =
+        Naming.Spark.builder()
+            .appName("my_awesome_app")
+            .command("execute_insert_into_hive_table")
+            .table("mydb_mytable")
+            .build();
+
+    assertEquals("my_awesome_app.execute_insert_into_hive_table.mydb_mytable", spark.getName());
+  }
+
+  @Test
+  void testSparkEmptyFieldsThrowException() {
+    assertThrows(IllegalArgumentException.class, () -> new Naming.Spark("", "cmd", "table"));
+  }
+
+  @Test
+  void testSparkNullFieldsThrowException() {
+    assertThrows(
+        NullPointerException.class,
+        () -> Naming.Spark.builder().appName(null).command("cmd").table("table").build());
+  }
+}

integration/spark/shared/src/main/java/io/openlineage/spark/api/naming/JobNameBuilder.java

@@ -7,6 +7,7 @@
 
 import static io.openlineage.spark.agent.util.DatabricksUtils.prettifyDatabricksJobName;
 
+import io.openlineage.client.job.Naming;
 import io.openlineage.spark.agent.util.DatabricksUtils;
 import io.openlineage.spark.api.JobNameSuffixProvider;
 import io.openlineage.spark.api.OpenLineageContext;
@@ -34,32 +35,27 @@ public static String build(OpenLineageContext context) {
     }
 
     Optional<SparkConf> sparkConf = context.getSparkContext().map(SparkContext::getConf);
-    StringBuilder jobNameBuilder =
-        new StringBuilder(applicationJobNameResolver.getJobName(context));
+    Naming.Spark.SparkBuilder jobNameBuilder =
+        Naming.Spark.builder().appName(applicationJobNameResolver.getJobName(context));
 
     sparkNodeName(context)
         .ifPresent(
             nodeName ->
-                jobNameBuilder
-                    .append(JOB_NAME_PARTS_SEPARATOR)
-                    .append(replaceDots(context, NameNormalizer.normalize(nodeName))));
+                jobNameBuilder.command(replaceDots(context, NameNormalizer.normalize(nodeName))));
 
     String jobName;
     if (context.getOpenLineageConfig().getJobName() != null
         && !context.getOpenLineageConfig().getJobName().getAppendDatasetName()) {
       // no need to append output dataset name
-      jobName = jobNameBuilder.toString();
+      jobName = jobNameBuilder.build().getName();
     } else {
       // append output dataset as job suffix
-      jobNameBuilder.append(
+      jobNameBuilder.table(
           getJobSuffix(context)
-              .map(
-                  suffix ->
-                      JOB_NAME_PARTS_SEPARATOR
-                          + suffix.replace(JOB_NAME_PARTS_SEPARATOR, INNER_SEPARATOR))
-              .orElse(""));
+              .map(suffix -> suffix.replace(JOB_NAME_PARTS_SEPARATOR, INNER_SEPARATOR))
+              .orElse(null));
 
-      jobName = jobNameBuilder.toString();
+      jobName = jobNameBuilder.build().getName();
       if (sparkConf.isPresent() && DatabricksUtils.isRunOnDatabricksPlatform(sparkConf.get())) {
         jobName = prettifyDatabricksJobName(sparkConf.get(), jobName);
       }