Package org.incenp.linkml.core

Class ConverterContext

  • public class ConverterContext
extends Object
    Global context for converting LinkML objects (as parsed from a JSON/YAML document) into their corresponding Java objects.

    An object of this class serves mostly two purposes.

    First, it holds a list of all the known LinkML classes, along with their respective converter objects. So whenever a converting encounters a slot expecting a value of type Foo (where Foo is a LinkML class), it can obtain from the context the converter it needs to convert the value of the slot into an instance of the Foo class.

    Second, it provides a solution to the problem of dereferencing entities that may not have been parsed/converted yet. For example, when parsing a class definition, we are likely to encounter a reference to a slot definition, but we may not have parsed that slot definition yet. We cannot solve that simply by ensuring that we always parse slot definitions first, because slot definitions may in turn contain references to a class definition (typically within the range slot). This context object will take care of resolving those references, either immediately if possible (if the referenced object has already been seen before), or in a post-parsing finalization step (when we are sure that all objects contained in the document have been seen, so all references should be resolvable).

    • Constructor Detail

      • ConverterContext

        public ConverterContext()

    • Method Detail

      • addConverter

        public void addConverter​(Class<?> type)
        Registers a converter for objects of the given class.
        Parameters:
        type - The class for which to register a converter. A default converter will be automatically created.

      • addConverter

        public void addConverter​(IConverter converter)
        Registers a pre-built converter.
        Parameters:
        converter - The converter to register.

      • getConverter

        public IConverter getConverter​(Class<?> type)
                        throws LinkMLRuntimeException
        Gets the converter for objects of the given type.
        Parameters:
        type - The type to query.
        Returns:
        The registered converter for the type, or null if no converter has been registered for that type.
        Throws:
        LinkMLRuntimeException - If the type is configured to use a custom converter that could not be instantiated.

      • getConverter

        public IConverter getConverter​(Slot slot)
                        throws LinkMLRuntimeException
        Gets the converter for the type of object expected by the given slot.
        Parameters:
        slot - The slot for which a converter is needed.
        Returns:
        The appropriate converter.
        Throws:
        LinkMLRuntimeException - If (1) the slot is configured to use a custom converter, but the custom converter could not be instantiated; or (2) if there is no known converter for the slot type.

      • addPrefix

        public void addPrefix​(String name,
                      String prefix)
        Registers a prefix.

        Any prefix declared here will become resolvable by the resolve(String) method.

        Parameters:
        name - The prefix name.
        prefix - The corresponding IRI prefix.

      • resolve

        public String resolve​(String name)
        Resolves a shortened identifier (“CURIE”) into a full-length IRI.
        Parameters:
        name - The shortened identifier to resolve.
        Returns:
        The resolved IRI, or the original String if (1) it was not a shortened identifier to begin with or (2) the prefix is unknown.

      • compact

        public String compact​(String iri)
        Compacts an IRI into a shortened identifier (“CURIE“).
        Parameters:
        iri - The IRI to shorten.
        Returns:
        The shortened identifier, or the original string if there no known suitable prefix for the given IRI.

      • getObject

        public <T> T getObject​(Class<T> type,
                       String name,
                       boolean create)
                throws LinkMLRuntimeException
        Dereferences a global object, optionally creating it if does not already exist.
        Type Parameters:
        T - The type of object to dereference.
        Parameters:
        type - The type of object to dereference.
        name - The name to resolve into a dereferenced object.
        create - If true, a new object of the given type and with the given name will be created and added to the global context if an object with that name did not already exist.
        Returns:
        The dereferenced object, or null if the object did not already exist and create is false.
        Throws:
        LinkMLRuntimeException - If the object type is not suitable for global objects, or if we cannot create the object as needed.

      • getObject

        public Object getObject​(Slot slot,
                        String name,
                        Object target)
                 throws LinkMLRuntimeException
        Dereferences a global object and assigns it to a slot on another object.

        If the desired object does not exist in the context, the assignment will take place when the finalizeAssignments() method is called.

        Parameters:
        slot - The slot to which to assign the dereferenced object.
        name - The name to resolve into a dereferenced object.
        target - The object to which to assign the dereferenced object.
        Returns:
        The dereferenced object, or null if the object does not exist in the context at the time this method is called.
        Throws:
        LinkMLRuntimeException - If the object type is not suitable for global objects, or if the retrieved object cannot be assigned to the slot.

      • getObjects

        public void getObjects​(Class<?> type,
                       List<String> names,
                       List<Object> target)
                throws LinkMLRuntimeException
        Dereferences several global objects and assigns them to a list.

        If any of the referenced objects does not exist in the context, it will be assigned to the target list when the finalizeAssignments() method is called.

        Parameters:
        type - The type of the objects to dereference.
        names - The names to resolve into dereferenced objects.
        target - The list to which the dereferenced objects should be assigned.
        Throws:
        LinkMLRuntimeException - If the object type is not suitable for global objects.

      • finalizeAssignments

        public void finalizeAssignments()
                         throws LinkMLRuntimeException
        Performs all delayed assignments.

        A delayed assignment is an assignment requested through the getObject(Slot, String, Object) or getObjects(Class, List, List) methods, which could not be performed at the time that method was called because the requested object was not known to the context yet.

        If a referenced object is still unknown when delayed assignments are performed, an empty object of the desired type and with the referenced identifier will be automatically created. Use finalizeAssignments(boolean) to treat missing references as an error instead.

        Throws:
        LinkMLRuntimeException - If an assignment cannot be performed.

      • finalizeAssignments

        public void finalizeAssignments​(boolean failOnMissing)
                         throws LinkMLRuntimeException
        Performs all delayed assignments, optionally failing if an assignment refers to a missing object.
        Parameters:
        failOnMissing - If true and a delayed assignment refers to an object that is either unknown in the global context, or of a different type than expected, this will be treated as a fatal error.
        Throws:
        LinkMLRuntimeException - If an assignment cannot be performed (including for an invalid reference, if failOnMissing is true.