Package com.evolveum.midpoint.prism

Interface PrismParser

All Known Subinterfaces:

PrismParserNoIO

All Known Implementing Classes:

PrismParserImplIO, PrismParserImplNoIO

public interface PrismParser

Parses a given input into prism or POJO objects. The interface is pretty straightforward; only two things are of interest: 1. how to determine the type of data to be retrieved, 2. how to determine the name of the item that is to be created (in case of prism items). For most cases, both can be determined from the input. E.g. if we are parsing a prism object that is rooted at the "user" XML element, it is clear that the type is c:UserType and the name is c:user. In other cases, the algorithms are the following: Data type determination: We collect all the available data, i.e. - explicit type specification in source data (xsi:type/@type), - itemDefinition provided by the caller, - item name in source data, - itemName provided by the caller, - typeName provided by the caller, - typeClass provided by the caller and take the most specific of these. In case of conflict we report an error. Data name determination: First name that is present takes precedence: 1. itemName 2. source data (if namespace is missing, it is filled from item definition) 3. name from itemDefinition 4. name from item definition derived from type name 5. name from item definition derived from type class General post-conditions: (For items as well as item values; and for all parsing methods.) - All recognizable definitions are set. - Prism context is set on all items and PCVs. - No unresolved raw values with known types are present.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	PrismParser.ObjectHandler

Method Summary

Modifier and Type	Method	Description
@NotNull PrismParser	compat()	Switches the parser into "compatibility" (or relaxed) parsing mode.
@NotNull PrismParser	context(@NotNull ParsingContext context)	Provides a parsing context for the parser.
PrismParser	convertMissingTypes()
@NotNull PrismParser	definition(ItemDefinition<?> itemDefinition)	Tells parser which definition to use when parsing item (or an item value).
@NotNull PrismParser	fastAddOperations()	Does not check for existing values during parsing.
@NotNull PrismParser	json()	Sets the language of the parser to be JSON.
@NotNull PrismParser	language(@Nullable String language)	For string inputs: sets the data language that the parser will try to parse; null means auto-detect.
@NotNull PrismParser	name(QName itemName)	Tells parser what name to use for parsed item.
<O extends Objectable> @NotNull PrismObject<O>	parse()	Parses the input as a prism object.
<IV extends PrismValue,ID extends ItemDefinition<?>> Item<IV,ID>	parseItem()	Parses the input as a prism item.
Object	parseItemOrRealValue()	Deprecated.
<IV extends PrismValue> IV	parseItemValue()	Parses the input as a prism value.
@NotNull List<PrismObject<? extends Objectable>>	parseObjects()	Parses the input as a collection of prism objects.
void	parseObjectsIteratively(@NotNull PrismParser.ObjectHandler handler)	Currently implemented for JSON/YAML only.
<T> T	parseRealValue()	Parses a real value.
<T> T	parseRealValue(@Nullable Class<T> clazz)	Parses a real value - either property or container value.
<T> javax.xml.bind.JAXBElement<T>	parseRealValueToJaxbElement()	Parses a real value and stores it into JAXBElement, using item name derived in the usual way.
RootXNode	parseToXNode()	Parses the input into RootXNode.
@NotNull PrismParser	strict()	Switches the parser into "strict" parsing mode.
@NotNull PrismParser	type(Class<?> typeClass)	Tells parser what data type to expect.
@NotNull PrismParser	type(QName typeName)	Tells parser what data type to expect.
@NotNull PrismParser	xml()	Sets the language of the parser to be XML.
@NotNull PrismParser	yaml()	Sets the language of the parser to be YAML.

Method Detail

language

@NotNull
@NotNull PrismParser language(@Nullable
                              @Nullable String language)

For string inputs: sets the data language that the parser will try to parse; null means auto-detect. For other kinds of input (DOM and XNode) the language is fixed to XML or none, respectively.

Parameters:

language - The language

Returns:

Updated parser.

xml

@NotNull
@NotNull PrismParser xml()

Sets the language of the parser to be XML.

Returns:

Updated parser.

json

@NotNull
@NotNull PrismParser json()

Sets the language of the parser to be JSON.

Returns:

Updated parser.

yaml

@NotNull
@NotNull PrismParser yaml()

Sets the language of the parser to be YAML.

Returns:

Updated parser.

context

@NotNull
@NotNull PrismParser context(@NotNull
                             @NotNull ParsingContext context)

Provides a parsing context for the parser. The context contains e.g. selection of strict/compat mode of operation (set by client) or a list of warnings (maintained by the parser).

Parameters:

context - The parsing context.

Returns:

Updated parser.

strict

@NotNull
@NotNull PrismParser strict()

Switches the parser into "strict" parsing mode.

Returns:

Updated parser.

compat

@NotNull
@NotNull PrismParser compat()

Switches the parser into "compatibility" (or relaxed) parsing mode. TODO description here

Returns:

Updated parser.

fastAddOperations

@NotNull
@NotNull PrismParser fastAddOperations()

Does not check for existing values during parsing. To be used in situations where the data can be trusted to not contain duplicates - for example, when reading from the repository.

definition

@NotNull
@NotNull PrismParser definition(ItemDefinition<?> itemDefinition)

Tells parser which definition to use when parsing item (or an item value). Optional.

Parameters:

itemDefinition - The definition

Returns:

Updated parser.

type

@NotNull
@NotNull PrismParser type(QName typeName)

Tells parser what data type to expect. Optional.

Parameters:

typeName - Data type to expect.

Returns:

Updated parser.

type

@NotNull
@NotNull PrismParser type(Class<?> typeClass)

Tells parser what data type to expect. Optional.

Parameters:

typeClass - Data type to expect.

Returns:

Updated parser.

name

@NotNull
@NotNull PrismParser name(QName itemName)

Tells parser what name to use for parsed item. Optional.

Parameters:

itemName - Item name to use.

Returns:

Updated parser.

parse

@NotNull
<O extends Objectable> @NotNull PrismObject<O> parse()
                                              throws SchemaException,
                                                     IOException

Parses the input as a prism object.

Returns:

The object.

Throws:

SchemaException

IOException

parseItem

<IV extends PrismValue,ID extends ItemDefinition<?>> Item<IV,ID> parseItem()
                                                                                throws SchemaException,
                                                                                       IOException

Parses the input as a prism item. (Object, container, reference, value.) May return raw property values as part of the prism structure, if definitions are not known.

Returns:

The item.

Throws:

SchemaException

IOException

parseItemValue

<IV extends PrismValue> IV parseItemValue()
                                   throws SchemaException,
                                          IOException

Parses the input as a prism value. (Container value, reference value, property value.) May return raw property values as part of the prism structure, if definitions are not known.

Returns:

The item.

Throws:

SchemaException

IOException

parseRealValue

<T> T parseRealValue(@Nullable
                     @Nullable Class<T> clazz)
              throws IOException,
                     SchemaException

Parses a real value - either property or container value.

Parameters:

clazz - Expected class of the data. May be null if unknown.

Returns:

Real value - POJO, Containerable, Objectable or Referencable.

Throws:

IOException

SchemaException

parseRealValue

<T> T parseRealValue()
              throws IOException,
                     SchemaException

Parses a real value. The class is not supplied by the caller, so it has to be determined from the data source.

Returns:

Real value - POJO, Containerable, Objectable or Referencable.

Throws:

IOException

SchemaException

parseRealValueToJaxbElement

<T> javax.xml.bind.JAXBElement<T> parseRealValueToJaxbElement()
                                                       throws IOException,
                                                              SchemaException

Parses a real value and stores it into JAXBElement, using item name derived in the usual way.

Throws:

IOException

SchemaException

parseToXNode

RootXNode parseToXNode()
                throws IOException,
                       SchemaException

Parses the input into RootXNode. This is a bit unusual approach, skipping the unmarshalling phase altogether. But it is useful at some places.

Returns:

RootXNode corresponding to the input.

Throws:

IOException

SchemaException

parseItemOrRealValue

@Deprecated
Object parseItemOrRealValue()
                     throws IOException,
                            SchemaException

Deprecated.

Parses either an item, or a real value. It depends on the type declaration or item name in the source data. 1) If explicit type is present, it is taken into account. If it corresponds to a prism item, the input is parsed as a prism item. Otherwise, it is parsed as a real value (containerable or simple POJO), if possible. 2) If there is no type, the item name is consulted. If it corresponds to a prism item, the input is parsed as a prism item. Otherwise, an exception is thrown. Pre-set parameters (itemDefinition, typeName, itemName) must NOT be present. Use with utmost care. If at all possible, avoid it.

Returns:

either prism item (Item) or a real value (Object)

Throws:

IOException

SchemaException

parseObjects

@NotNull
@NotNull List<PrismObject<? extends Objectable>> parseObjects()
                                                       throws SchemaException,
                                                              IOException

Parses the input as a collection of prism objects. For XML the input must be formatted as a collection of objects (TODO change this). For other languages the input may contain one or more objects.

Returns:

A list of objects.

Throws:

SchemaException

IOException

parseObjectsIteratively

void parseObjectsIteratively(@NotNull
                             @NotNull PrismParser.ObjectHandler handler)
                      throws SchemaException,
                             IOException

Currently implemented for JSON/YAML only. For XML, use old Validator code.

Parameters:

handler -

Throws:

SchemaException

IOException

convertMissingTypes

PrismParser convertMissingTypes()