Package org.incenp.linkml.core

Class ObjectConverter

java.lang.Object

org.incenp.linkml.core.ObjectConverter

All Implemented Interfaces:

IConverter

Direct Known Subclasses:

ClassDefinitionConverter

public class ObjectConverter
extends Object
implements IConverter

A generic converter to convert “raw objects” (as obtained from a JSON/YAML parser) into instances of LinkML classes.

Field Summary

Fields

Modifier and Type	Field	Description
protected ClassInfo	klass

Constructor Summary

Constructors

Constructor	Description
ObjectConverter(Class<?> klass)	Creates a new converter for objects of the specified type.

Method Summary

Modifier and Type	Method	Description
Object	convert(Object raw, ConverterContext ctx)	Converts a raw object into a LinkML object.
Object	convert(Map<String,Object> raw, String id, ConverterContext ctx)	Converts a raw map into a new instance of a LinkML object.
Object	convert(Map<String,Object> raw, ConverterContext ctx)	Converts a raw map into a new instance of a LinkML object.
void	convertForSlot(Object raw, Object dest, Slot slot, ConverterContext ctx)	Converts the value of a single slot and assigns it to the target object.
void	convertTo(Object raw, Object dest, ConverterContext ctx)	Converts a raw object into an instance of a LinkML object, where the object already exists.
void	convertTo(Map<String,Object> rawMap, Object dest, ConverterContext ctx)	Converts a raw map into an instance of a LinkML object, where the object already exists.
protected String	getGlobalIdentifier(Object raw, ConverterContext ctx)	Converts the given raw object into an identifier for the target object type.
protected List<String>	getGlobalIdentifierList(Object raw, ConverterContext ctx)	Converts the given list of raw objects into identifiers for the target object type.
Class<?>	getType()	Gets the type of object that this converter can convert a raw object into.
protected List<Object>	normaliseList(Object raw, InliningMode expected)	Normalises a raw multi-valued slot.
Map<String,Object>	serialise(Object object, boolean withIdentifier, ConverterContext ctx)	Converts a LinkML object into a raw object.
Object	serialise(Object object, ConverterContext ctx)	Converts a LinkML object into a raw object.
Object	serialiseForSlot(Object object, Slot slot, ConverterContext ctx)	Converts a LinkML object into a raw object, when the object is the value of a specific LinkML slot.
protected Object	toIdentifier(Object object, ConverterContext ctx)	Gets the unique identifier for the given object.
protected List<Object>	toList(Object value)	Checks that a raw object is a list, and casts it as such.
protected Map<String,Object>	toMap(Object value)	Checks that a raw object is a String-keyed map, and casts it as such.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

klass

protected ClassInfo klass

Constructor Detail

ObjectConverter

public ObjectConverter(Class<?> klass)

Creates a new converter for objects of the specified type.

Parameters:

klass - The type into which to convert raw objects.

Method Detail

getType

public Class<?> getType()

Description copied from interface: IConverter

Gets the type of object that this converter can convert a raw object into.

Specified by:

getType in interface IConverter

convertTo

public void convertTo(Map<String,Object> rawMap,
                      Object dest,
                      ConverterContext ctx)
               throws LinkMLRuntimeException

Converts a raw map into an instance of a LinkML object, where the object already exists.

Parameters:

rawMap - The raw map to convert.

dest - The instance of the LinkML object whose slots should be filled with values from the raw map.

ctx - The global converter context.

Throws:

LinkMLRuntimeException - If a slot of the dest object cannot be assigned.

convertTo

public void convertTo(Object raw,
                      Object dest,
                      ConverterContext ctx)
               throws LinkMLRuntimeException

Converts a raw object into an instance of a LinkML object, where the object already exists.

This method is similar to convertTo(Map, Object, ConverterContext), but accepts a Object-typed raw value and takes care of checking that the value is actually a map. If the raw object is null, this method is a no-op.

Parameters:

raw - The raw object to convert.

dest - The instance of the LinkML object whose slots should be filled with values from the raw object.

ctx - The global converter context.

Throws:

LinkMLRuntimeException - If either (1) raw is not a map, or (2) a slot of the dest object cannot be assigned.

convert

public Object convert(Object raw,
                      ConverterContext ctx)
               throws LinkMLRuntimeException

Description copied from interface: IConverter

Converts a raw object into a LinkML object.

Specified by:

convert in interface IConverter

Parameters:

raw - The raw object to convert.

ctx - The global converter context.

Returns:

The converted object.

Throws:

LinkMLRuntimeException - If the converter cannot convert the given value.

convert

public Object convert(Map<String,Object> raw,
                      ConverterContext ctx)
               throws LinkMLRuntimeException

Converts a raw map into a new instance of a LinkML object.

If the object to create is an “identifiable” object, then the identifier is expected to be found within the provided raw map.

Parameters:

raw - The raw map to convert.

ctx - The global converter context.

Returns:

The newly created object.

Throws:

LinkMLRuntimeException - If (1) the object cannot be created, (2) one of its slots cannot be assigned, or (3) the object requires an identifier that was not found within the raw map.

convert

public Object convert(Map<String,Object> raw,
                      String id,
                      ConverterContext ctx)
               throws LinkMLRuntimeException

Converts a raw map into a new instance of a LinkML object.

Parameters:

raw - The raw map to convert.

id - The global identifier of the new object. May be null if the object is not a “ globally identifiable” object (it has no identifier slot).

ctx - The global converter context.

Returns:

The newly created object.

Throws:

LinkMLRuntimeException - If the object cannot be created, or one of its slots cannot be assigned.

convertForSlot

public void convertForSlot(Object raw,
                           Object dest,
                           Slot slot,
                           ConverterContext ctx)
                    throws LinkMLRuntimeException

Converts the value of a single slot and assigns it to the target object.

Specified by:

convertForSlot in interface IConverter

Parameters:

raw - The raw value of the slot.

slot - The slot to which the value should be assigned.

dest - The object whose slots should be assigned.

ctx - The global converter context.

Throws:

LinkMLRuntimeException - If (1) the raw value does not match the expected type for the slot, or (2) the converted value cannot be assigned.

getGlobalIdentifier

protected String getGlobalIdentifier(Object raw,
                                     ConverterContext ctx)
                              throws LinkMLRuntimeException

Converts the given raw object into an identifier for the target object type.

This invokes whatever converter is configured for the identifier slot of the target type. Most often it should be the StringConverter (as identifier slots are mostly expected to be string-typed), but it could also be the CurieConverter, if the identifier slot is typed as a uriOrCurie.

Parameters:

raw - The raw identifier to convert.

ctx - The global converter context.

Returns:

The converted identifier.

Throws:

LinkMLRuntimeException - If any error occurs during the conversion attempt.

getGlobalIdentifierList

protected List<String> getGlobalIdentifierList(Object raw,
                                               ConverterContext ctx)
                                        throws LinkMLRuntimeException

Converts the given list of raw objects into identifiers for the target object type.

This method does basically the same thing as getGlobalIdentifier(Object, ConverterContext) for every raw object in the provided list.

Parameters:

raw - The raw object to convert. It is expected to be a list containing the raw identifiers.

ctx - The global converter context.

Returns:

The list of converter identifiers.

Throws:

LinkMLRuntimeException - If any error occurs during the conversion attempt. This includes the case where the provided raw object is not a list.

serialise

public Object serialise(Object object,
                        ConverterContext ctx)
                 throws LinkMLRuntimeException

Description copied from interface: IConverter

Converts a LinkML object into a raw object.

Specified by:

serialise in interface IConverter

Parameters:

object - The LinkML object to convert.

ctx - The global converter context.

Returns:

The raw object that represents the original LinkML object.

Throws:

LinkMLRuntimeException - If the converter cannot convert the given object.

serialise

public Map<String,Object> serialise(Object object,
                                          boolean withIdentifier,
                                          ConverterContext ctx)
                                   throws LinkMLRuntimeException

Converts a LinkML object into a raw object. This serializes an object into a map, with the option of including the object’s unique identifier into the map.

Parameters:

object - The LinkML object to convert.

withIdentifier - If false, the slot for the object’s unique identifier (whether is it local or global) is not serialised; this avoids repeating the identifier when the object is serialised in such a way that the identifier is already provided elsewhere (typically as a dict, yielding what the LinkML documentation calls the “CompactDict” serialisation). This has no effect if the object has no identifier or key slot.

ctx - The global converter context.

Returns:

The map that represents the original LinkML object.

Throws:

LinkMLRuntimeException - If the converter cannot convert the given object.

serialiseForSlot

public Object serialiseForSlot(Object object,
                               Slot slot,
                               ConverterContext ctx)
                        throws LinkMLRuntimeException

Description copied from interface: IConverter

Converts a LinkML object into a raw object, when the object is the value of a specific LinkML slot.

We need such a method because the way to serialise a LinkML object into a raw object will sometimes depend on the slot to which the object belongs (the slot of which it is a value), especially with respect to inlining.

Specified by:

serialiseForSlot in interface IConverter

Parameters:

object - The LinkML object to convert.

slot - The slot that the given object is a value of.

ctx - The global converter context.

Returns:

The raw object that represents the original LinkML object.

Throws:

LinkMLRuntimeException - If the converter cannot convert the given object.

toIdentifier

protected Object toIdentifier(Object object,
                              ConverterContext ctx)
                       throws LinkMLRuntimeException

Gets the unique identifier for the given object.

The identifier may be a local identifier (key) or a global one (proper identifier in the LinkML sense).

Parameters:

object - The object for which to get the identifier.

Returns:

The unique identifier for the object.

Throws:

LinkMLRuntimeException - If the object is not of the expected type, or if it has no identifier value.

toMap

protected Map<String,Object> toMap(Object value)
                                  throws LinkMLRuntimeException

Checks that a raw object is a String-keyed map, and casts it as such.

Parameters:

value - The raw object to cast.

Returns:

The input object, cast into a String-keyed map.

Throws:

LinkMLRuntimeException - If the raw object is not a String-keyed map.

toList

protected List<Object> toList(Object value)
                       throws LinkMLRuntimeException

Checks that a raw object is a list, and casts it as such.

Parameters:

value - The raw object to cast.

Returns:

The input object, cast into a list.

Throws:

LinkMLRuntimeException - If the raw object is not in fact a list.

normaliseList

protected List<Object> normaliseList(Object raw,
                                     InliningMode expected)
                              throws LinkMLRuntimeException

Normalises a raw multi-valued slot.

This is mostly a convenience method to make the job of convertForSlot(Object, Object, Slot, ConverterContext) easier. Given the raw value of a multi-valued slot, it always provides a list representation of it, whether the value has indeed been serialised as a list or as any kind of dict.

This incidentally implements the non-repair collection form normalisations described in the LinkML specification.

Parameters:

raw - The raw value to convert.

expected - The expected inlining mode, according to the slot for which the values are intended.

Returns:

A list with the raw values. This may be the original value (simply casted as a list) if it already was a list to begin with, or a new list transformed from whatever actual serialisation was used.

Throws:

LinkMLRuntimeException - (1) If the slot expected a list serialisation and we got any kind of dict, or the other way round. (2) If we got something that looks like a SimpleDict, for a class that does not support this kind of serialisation. (3) Or if we get anything else than a list or a dict.