Add reference ids

legend-pure-core/legend-pure-m3-core/src/main/java/org/finos/legend/pure/m3/serialization/compiler/reference/InvalidReferenceIdException.java

@@ -0,0 +1,48 @@
+// Copyright 2025 Goldman Sachs
+//
+// Licensed 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.finos.legend.pure.m3.serialization.compiler.reference;
+
+/**
+ * Exception arising when a reference id cannot be resolved because the id is invalid.
+ */
+public class InvalidReferenceIdException extends ReferenceIdResolutionException
+{
+    public InvalidReferenceIdException(String referenceId, String message, Throwable cause)
+    {
+        super(referenceId, message, cause);
+    }
+
+    public InvalidReferenceIdException(String referenceId, String message)
+    {
+        super(referenceId, message);
+    }
+
+    public InvalidReferenceIdException(String referenceId, Throwable cause)
+    {
+        this(referenceId, buildMessage(referenceId), cause);
+    }
+
+    public InvalidReferenceIdException(String referenceId)
+    {
+        this(referenceId, buildMessage(referenceId));
+    }
+
+    private static String buildMessage(String referenceId)
+    {
+        return (referenceId == null) ?
+               "Invalid reference id: null" :
+               ("Invalid reference id: \"" + referenceId + "\"");
+    }
+}

legend-pure-core/legend-pure-m3-core/src/main/java/org/finos/legend/pure/m3/serialization/compiler/reference/ReferenceIdException.java

@@ -0,0 +1,36 @@
+// Copyright 2025 Goldman Sachs
+//
+// Licensed 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.finos.legend.pure.m3.serialization.compiler.reference;
+
+/**
+ * Base class for all exceptions related to reference ids.
+ */
+public class ReferenceIdException extends RuntimeException
+{
+    public ReferenceIdException(String message, Throwable cause)
+    {
+        super(message, cause);
+    }
+
+    public ReferenceIdException(String message)
+    {
+        super(message);
+    }
+
+    public ReferenceIdException(Throwable cause)
+    {
+        super(cause);
+    }
+}

legend-pure-core/legend-pure-m3-core/src/main/java/org/finos/legend/pure/m3/serialization/compiler/reference/ReferenceIdExtension.java

@@ -0,0 +1,26 @@
+// Copyright 2025 Goldman Sachs
+//
+// Licensed 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.finos.legend.pure.m3.serialization.compiler.reference;
+
+import org.finos.legend.pure.m3.navigation.ProcessorSupport;
+
+public interface ReferenceIdExtension
+{
+    int version();
+
+    ReferenceIdProvider newProvider(ProcessorSupport processorSupport);
+
+    ReferenceIdResolver newResolver(ProcessorSupport processorSupport);
+}

legend-pure-core/legend-pure-m3-core/src/main/java/org/finos/legend/pure/m3/serialization/compiler/reference/ReferenceIdProvider.java

@@ -0,0 +1,37 @@
+// Copyright 2025 Goldman Sachs
+//
+// Licensed 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.finos.legend.pure.m3.serialization.compiler.reference;
+
+import org.finos.legend.pure.m4.coreinstance.CoreInstance;
+
+public interface ReferenceIdProvider
+{
+    /**
+     * Version of the {@link ReferenceIdExtension} that this provider is associated with.
+     *
+     * @return extension version
+     */
+    int version();
+
+    /**
+     * Get an id for the given reference instance. If no id can be found or computed for the reference instance, then
+     * the implementing class should throw a {@link ReferenceIdProvisionException} with an explanation of why not.
+     *
+     * @param reference reference instance
+     * @return reference id
+     * @throws ReferenceIdProvisionException if no id can be found or computed
+     */
+    String getReferenceId(CoreInstance reference) throws ReferenceIdProvisionException;
+}

legend-pure-core/legend-pure-m3-core/src/main/java/org/finos/legend/pure/m3/serialization/compiler/reference/ReferenceIdProvisionException.java

@@ -0,0 +1,31 @@
+// Copyright 2025 Goldman Sachs
+//
+// Licensed 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.finos.legend.pure.m3.serialization.compiler.reference;
+
+/**
+ * Exception that arises when a reference id cannot be provided for an instance.
+ */
+public class ReferenceIdProvisionException extends ReferenceIdException
+{
+    public ReferenceIdProvisionException(String message, Throwable cause)
+    {
+        super(message, cause);
+    }
+
+    public ReferenceIdProvisionException(String message)
+    {
+        super(message);
+    }
+}

legend-pure-core/legend-pure-m3-core/src/main/java/org/finos/legend/pure/m3/serialization/compiler/reference/ReferenceIdResolutionException.java

@@ -0,0 +1,45 @@
+// Copyright 2025 Goldman Sachs
+//
+// Licensed 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.finos.legend.pure.m3.serialization.compiler.reference;
+
+/**
+ * Base class for all exceptions related to reference id resolution.
+ */
+public class ReferenceIdResolutionException extends ReferenceIdException
+{
+    private final String referenceId;
+
+    public ReferenceIdResolutionException(String referenceId, String message, Throwable cause)
+    {
+        super(message, cause);
+        this.referenceId = referenceId;
+    }
+
+    public ReferenceIdResolutionException(String referenceId, String message)
+    {
+        super(message);
+        this.referenceId = referenceId;
+    }
+
+    /**
+     * Get the reference id involved in the exception. Note that this may be null.
+     *
+     * @return reference id (possibly null)
+     */
+    public String getReferenceId()
+    {
+        return this.referenceId;
+    }
+}

legend-pure-core/legend-pure-m3-core/src/main/java/org/finos/legend/pure/m3/serialization/compiler/reference/ReferenceIdResolver.java

@@ -0,0 +1,39 @@
+// Copyright 2025 Goldman Sachs
+//
+// Licensed 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.finos.legend.pure.m3.serialization.compiler.reference;
+
+import org.finos.legend.pure.m4.coreinstance.CoreInstance;
+
+public interface ReferenceIdResolver
+{
+    /**
+     * Version of the {@link ReferenceIdExtension} that this resolver is associated with.
+     *
+     * @return extension version
+     */
+    int version();
+
+    /**
+     * Resolve the reference for the given id. If the id is invalid, the implementing class should throw an
+     * {@link InvalidReferenceIdException}. If the id cannot be resolved, the implementing class should throw an
+     * {@link UnresolvableReferenceIdException}.
+     *
+     * @param referenceId reference id
+     * @return reference instance
+     * @throws InvalidReferenceIdException if the id is invalid
+     * @throws UnresolvableReferenceIdException if the id cannot be resolved
+     */
+    CoreInstance resolveReference(String referenceId) throws InvalidReferenceIdException, UnresolvableReferenceIdException;
+}