001package ca.uhn.fhir.parser;
002
003import ca.uhn.fhir.parser.json.JsonLikeValue.ScalarType;
004import ca.uhn.fhir.parser.json.JsonLikeValue.ValueType;
005
006/*
007 * #%L
008 * HAPI FHIR - Core Library
009 * %%
010 * Copyright (C) 2014 - 2017 University Health Network
011 * %%
012 * Licensed under the Apache License, Version 2.0 (the "License");
013 * you may not use this file except in compliance with the License.
014 * You may obtain a copy of the License at
015 * 
016 * http://www.apache.org/licenses/LICENSE-2.0
017 * 
018 * Unless required by applicable law or agreed to in writing, software
019 * distributed under the License is distributed on an "AS IS" BASIS,
020 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
021 * See the License for the specific language governing permissions and
022 * limitations under the License.
023 * #L%
024 */
025
026/**
027 * Error handler
028 */
029public interface IParserErrorHandler {
030
031        /**
032         * Invoked when a contained resource is parsed that has no ID specified (and is therefore invalid)
033         * 
034         * @param theLocation
035         *           The location in the document. WILL ALWAYS BE NULL currently, as this is not yet implemented, but this parameter is included so that locations can be added in the future without
036         *           changing the API.
037         * @since 2.0
038         */
039        void containedResourceWithNoId(IParseLocation theLocation);
040
041        /**
042         * Invoked if the wrong type of element is found while parsing JSON. For example if a given element is
043         * expected to be a JSON Object and is a JSON array
044         * @param theLocation
045         *           The location in the document. Note that this may be <code>null</code> as the ParseLocation feature is experimental. Use with caution, as the API may change. 
046         * @param theElementName
047         *           The name of the element that was found.
048         * @param theExpectedValueType The datatype that was expected at this location
049         * @param theExpectedScalarType If theExpectedValueType is {@link ValueType#SCALAR}, this is the specific scalar type expected. Otherwise this parameter will be null.
050         * @param theFoundValueType The datatype that was found at this location
051         * @param theFoundScalarType If theFoundValueType is {@link ValueType#SCALAR}, this is the specific scalar type found. Otherwise this parameter will be null.
052         * 
053         * @since 2.2
054         */
055        void incorrectJsonType(IParseLocation theLocation, String theElementName, ValueType theExpectedValueType, ScalarType theExpectedScalarType, ValueType theFoundValueType, ScalarType theFoundScalarType);
056
057        /**
058         * The parser detected an atttribute value that was invalid (such as: empty "" values are not permitted)
059         * 
060         * @param theLocation
061         *           The location in the document. Note that this may be <code>null</code> as the ParseLocation feature is experimental. Use with caution, as the API may change. 
062         * @param theValue The actual value
063         * @param theError A description of why the value was invalid
064         * @since 2.2
065         */
066        void invalidValue(IParseLocation theLocation, String theValue, String theError);
067
068        /**
069         * Resource was missing a required element
070         * 
071         * @param theLocation
072         *           The location in the document. Note that this may be <code>null</code> as the ParseLocation feature is experimental. Use with caution, as the API may change. 
073         * @param theReference The actual invalid reference (e.g. "#3")
074         * @since 2.1
075         */
076        void missingRequiredElement(IParseLocation theLocation, String theElementName);
077
078        /**
079         * Invoked when an element repetition (e.g. a second repetition of something) is found for a field
080         * which is non-repeating.
081         * 
082         * @param theLocation
083         *           The location in the document. Note that this may be <code>null</code> as the ParseLocation feature is experimental. Use with caution, as the API may change. 
084         * @param theElementName
085         *           The name of the element that was found.
086         * @since 1.2
087         */
088        void unexpectedRepeatingElement(IParseLocation theLocation, String theElementName);
089
090        /**
091         * Invoked when an unknown element is found in the document.
092         * 
093         * @param theLocation
094         *           The location in the document. Note that this may be <code>null</code> as the ParseLocation feature is experimental. Use with caution, as the API may change. 
095         * @param theAttributeName
096         *           The name of the attribute that was found.
097         */
098        void unknownAttribute(IParseLocation theLocation, String theAttributeName);
099
100        /**
101         * Invoked when an unknown element is found in the document.
102         * 
103         * @param theLocation
104         *           The location in the document. Note that this may be <code>null</code> as the ParseLocation feature is experimental. Use with caution, as the API may change. 
105         * @param theElementName
106         *           The name of the element that was found.
107         */
108        void unknownElement(IParseLocation theLocation, String theElementName);
109
110        /**
111         * Resource contained a reference that could not be resolved and needs to be resolvable (e.g. because
112         * it is a local reference to an unknown contained resource)
113         * 
114         * @param theLocation
115         *           The location in the document. Note that this may be <code>null</code> as the ParseLocation feature is experimental. Use with caution, as the API may change. 
116         * @param theReference The actual invalid reference (e.g. "#3")
117         * @since 2.0
118         */
119        void unknownReference(IParseLocation theLocation, String theReference);
120
121        /**
122         * For now this is an empty interface. Error handling methods include a parameter of this
123         * type which will currently always be set to null. This interface is included here so that
124         * locations can be added to the API in a future release without changing the API.
125         */
126        public interface IParseLocation {
127
128                /**
129                 * Returns the name of the parent element (the element containing the element currently being parsed)
130                 * @since 2.1
131                 */
132                String getParentElementName();
133                
134        }
135
136}