mbeckerle commented on code in PR #1112: URL: https://github.com/apache/daffodil/pull/1112#discussion_r1390326486
########## daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/api/Metadata.scala: ########## @@ -0,0 +1,274 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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.apache.daffodil.runtime1.api + +import scala.xml.NamespaceBinding + +import org.apache.daffodil.lib.xml.NamedQName +import org.apache.daffodil.runtime1.dpath.PrimTypeNode + +/** + * This is the supportable API for access to the RuntimeData structures + * which provide access to static information about a given . + * + * This is used to interface other data processing fabrics to Daffodil + * data and metadata, by mapping to/from these metadata objects. + */ +trait Metadata { + + /** + * Provides the file context of a metadata component. This refers to the specific + * DFDL schema file where the corresponding DFDL schema text resides corresponding + * to this metadata object. + * <p/> + * This is for use in diagnostic messaging. It is not the actual file URI, because + * those may contain personal-identifying information about the person/acccount and + * system that compiled the schema. It will provide enough content about the file URI that + * a user will be able to identify which file, but some prefix of the path + * components trimmed to make it of a manageable length. + * <p/> + * Used along with [[org.apache.daffodil.runtime1.api.Metadata.schemaFileLineNumber]] + * and [[org.apache.daffodil.runtime1.api.Metadata.schemaFileLineColumnNumber]], + * this can give a precise location in the DFDL schema file. + * @return a string containing the file information, or null if unknown. + */ + def schemaFileInfo: String + + /** + * Provides the line number to go with [[org.apache.daffodil.runtime1.api.Metadata.schemaFileInfo]]. + * @return the line number as a string, or null if unknown. + */ + def schemaFileLineNumber: String + + /** + * Provides the column number within the text line, to go with [[org.apache.daffodil.runtime1.api.Metadata.schemaFileLineNumber]]. + * @return the column number within the text line, as a string, or null if unknown. + */ + def schemaFileLineColumnNumber: String + + def path: String + + /** + * The name of the schema component, in a form suitable for diagnostic messages. + * Unnamed components like sequence or choice groups have a diagnosticDebugName, despite not having + * any actual name. + * @return the name of the component, suitable for use in diagnostic messages. + */ + def diagnosticDebugName: String + + /** + * The standard conversion of the metadata component to a string. + * Unless overridden this uses the [[org.apache.daffodil.runtime1.api.Metadata.diagnosticDebugName]]. + * @return string representation of this metadata component. + */ + override def toString = diagnosticDebugName +} + +/* + * Provides metadata access that is common to all Terms, which include + * Elements of simple or complex type, as well as the Sequence and Choice groups. + */ +trait TermMetadata extends Metadata { + // nothing here +} + +/** + * Common metadata access for all elements, of simple or complex type. + */ +trait ElementMetadata extends TermMetadata { + + /** + * @return the name of this element. In the case of a global/qualified name, this is only the local + * part of the QName. + */ + def name: String + + /** + * @return the namespace URI as a string, or null if no namespace. + */ + def namespace: String + + /** + * @return the namespace bindings needed to construct an XML element from a Daffodil infoset + * element of simple or complex type. + */ + def minimizedScope: NamespaceBinding + + /** + * @return the namespace prefix part of the XML QName of this component, or null if there + * is no prefix defined or no namespace. + */ + def prefix: String + + /** + * @return true if two or more occurrences are possible. + * Note that having only 0 or 1 occurrence is not considered an array, + * but rather an optional element. + */ + def isArray: Boolean + + /** + * @return true if only 0 or 1 occurrence are possible. + */ + def isOptional: Boolean + + /** + * @return + */ + def namedQName: NamedQName Review Comment: This should go away. The only added method needed is toQName which returns a string and we can get this class out of the API. ########## daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/api/Metadata.scala: ########## @@ -0,0 +1,274 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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.apache.daffodil.runtime1.api + +import scala.xml.NamespaceBinding + +import org.apache.daffodil.lib.xml.NamedQName +import org.apache.daffodil.runtime1.dpath.PrimTypeNode + +/** + * This is the supportable API for access to the RuntimeData structures + * which provide access to static information about a given . + * + * This is used to interface other data processing fabrics to Daffodil + * data and metadata, by mapping to/from these metadata objects. + */ +trait Metadata { + + /** + * Provides the file context of a metadata component. This refers to the specific + * DFDL schema file where the corresponding DFDL schema text resides corresponding + * to this metadata object. + * <p/> + * This is for use in diagnostic messaging. It is not the actual file URI, because + * those may contain personal-identifying information about the person/acccount and + * system that compiled the schema. It will provide enough content about the file URI that + * a user will be able to identify which file, but some prefix of the path + * components trimmed to make it of a manageable length. + * <p/> + * Used along with [[org.apache.daffodil.runtime1.api.Metadata.schemaFileLineNumber]] + * and [[org.apache.daffodil.runtime1.api.Metadata.schemaFileLineColumnNumber]], + * this can give a precise location in the DFDL schema file. + * @return a string containing the file information, or null if unknown. + */ + def schemaFileInfo: String + + /** + * Provides the line number to go with [[org.apache.daffodil.runtime1.api.Metadata.schemaFileInfo]]. + * @return the line number as a string, or null if unknown. + */ + def schemaFileLineNumber: String + + /** + * Provides the column number within the text line, to go with [[org.apache.daffodil.runtime1.api.Metadata.schemaFileLineNumber]]. + * @return the column number within the text line, as a string, or null if unknown. + */ + def schemaFileLineColumnNumber: String + + def path: String + + /** + * The name of the schema component, in a form suitable for diagnostic messages. + * Unnamed components like sequence or choice groups have a diagnosticDebugName, despite not having + * any actual name. + * @return the name of the component, suitable for use in diagnostic messages. + */ + def diagnosticDebugName: String + + /** + * The standard conversion of the metadata component to a string. + * Unless overridden this uses the [[org.apache.daffodil.runtime1.api.Metadata.diagnosticDebugName]]. + * @return string representation of this metadata component. + */ + override def toString = diagnosticDebugName +} + +/* + * Provides metadata access that is common to all Terms, which include + * Elements of simple or complex type, as well as the Sequence and Choice groups. + */ +trait TermMetadata extends Metadata { + // nothing here +} + +/** + * Common metadata access for all elements, of simple or complex type. + */ +trait ElementMetadata extends TermMetadata { + + /** + * @return the name of this element. In the case of a global/qualified name, this is only the local + * part of the QName. + */ + def name: String + + /** + * @return the namespace URI as a string, or null if no namespace. + */ + def namespace: String + + /** + * @return the namespace bindings needed to construct an XML element from a Daffodil infoset + * element of simple or complex type. + */ + def minimizedScope: NamespaceBinding + + /** + * @return the namespace prefix part of the XML QName of this component, or null if there + * is no prefix defined or no namespace. + */ + def prefix: String + + /** + * @return true if two or more occurrences are possible. + * Note that having only 0 or 1 occurrence is not considered an array, + * but rather an optional element. + */ + def isArray: Boolean + + /** + * @return true if only 0 or 1 occurrence are possible. + */ + def isOptional: Boolean + + /** + * @return + */ + def namedQName: NamedQName + + /** + * @return true if the element is declared to be nillable. + */ + def isNillable: Boolean + + /** + * Provides access to the runtime properties. This is an extended collection of + * name-value pairs which are associated with a schema component. + * <p/> + * Runtime properties are intended to use for new ad-hoc property extensions to + * DFDL. These name-value pairs are visible to infoset outputters as well. + * + * @return a java-compatible map of name-value pairs. + */ + def runtimeProperties: java.util.Map[String, String] + +} + +/** + * Access to metadata values exclusive to elements of complex type. + */ +trait ComplexElementMetadata extends ElementMetadata { + + /** + * @return an ordered sequence of the child elements within this complex type regardless + * of their nesting within sequence and choice groups. + */ + def childMetadata: Seq[ElementMetadata] +} + +/** + * Access to metadata values exclusive to elements of simple type. + */ +trait SimpleElementMetadata extends ElementMetadata { + + /** + * The primitive type of this element as a string. + * + * @return one of Boolean, Double, Float, Date, Time, DateTime, String, AnyURI, HexBinary, Decimal, + * Integer, NonNegativeInteger, Byte, Short, Int, Long, UnsignedByte, UnsignedShort, + * UnsignedInt, UnsignedLong as a string. Note the initial upper-case letter in all these + * type names. + */ + def primType: PrimTypeNode Review Comment: This method is also problematic. It exposes PrimTypeNode, which we don't want on our API. ########## daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/api/Metadata.scala: ########## @@ -0,0 +1,274 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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.apache.daffodil.runtime1.api + +import scala.xml.NamespaceBinding + +import org.apache.daffodil.lib.xml.NamedQName +import org.apache.daffodil.runtime1.dpath.PrimTypeNode + +/** + * This is the supportable API for access to the RuntimeData structures + * which provide access to static information about a given . + * + * This is used to interface other data processing fabrics to Daffodil + * data and metadata, by mapping to/from these metadata objects. + */ +trait Metadata { + + /** + * Provides the file context of a metadata component. This refers to the specific + * DFDL schema file where the corresponding DFDL schema text resides corresponding + * to this metadata object. + * <p/> + * This is for use in diagnostic messaging. It is not the actual file URI, because + * those may contain personal-identifying information about the person/acccount and + * system that compiled the schema. It will provide enough content about the file URI that + * a user will be able to identify which file, but some prefix of the path + * components trimmed to make it of a manageable length. + * <p/> + * Used along with [[org.apache.daffodil.runtime1.api.Metadata.schemaFileLineNumber]] + * and [[org.apache.daffodil.runtime1.api.Metadata.schemaFileLineColumnNumber]], + * this can give a precise location in the DFDL schema file. + * @return a string containing the file information, or null if unknown. + */ + def schemaFileInfo: String + + /** + * Provides the line number to go with [[org.apache.daffodil.runtime1.api.Metadata.schemaFileInfo]]. + * @return the line number as a string, or null if unknown. + */ + def schemaFileLineNumber: String + + /** + * Provides the column number within the text line, to go with [[org.apache.daffodil.runtime1.api.Metadata.schemaFileLineNumber]]. + * @return the column number within the text line, as a string, or null if unknown. + */ + def schemaFileLineColumnNumber: String + + def path: String Review Comment: Needs scaladoc ########## daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/api/Metadata.scala: ########## @@ -0,0 +1,274 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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.apache.daffodil.runtime1.api + +import scala.xml.NamespaceBinding + +import org.apache.daffodil.lib.xml.NamedQName +import org.apache.daffodil.runtime1.dpath.PrimTypeNode + +/** + * This is the supportable API for access to the RuntimeData structures + * which provide access to static information about a given . + * + * This is used to interface other data processing fabrics to Daffodil + * data and metadata, by mapping to/from these metadata objects. + */ +trait Metadata { + + /** + * Provides the file context of a metadata component. This refers to the specific + * DFDL schema file where the corresponding DFDL schema text resides corresponding + * to this metadata object. + * <p/> + * This is for use in diagnostic messaging. It is not the actual file URI, because + * those may contain personal-identifying information about the person/acccount and + * system that compiled the schema. It will provide enough content about the file URI that + * a user will be able to identify which file, but some prefix of the path + * components trimmed to make it of a manageable length. + * <p/> + * Used along with [[org.apache.daffodil.runtime1.api.Metadata.schemaFileLineNumber]] + * and [[org.apache.daffodil.runtime1.api.Metadata.schemaFileLineColumnNumber]], + * this can give a precise location in the DFDL schema file. + * @return a string containing the file information, or null if unknown. + */ + def schemaFileInfo: String + + /** + * Provides the line number to go with [[org.apache.daffodil.runtime1.api.Metadata.schemaFileInfo]]. + * @return the line number as a string, or null if unknown. + */ + def schemaFileLineNumber: String + + /** + * Provides the column number within the text line, to go with [[org.apache.daffodil.runtime1.api.Metadata.schemaFileLineNumber]]. + * @return the column number within the text line, as a string, or null if unknown. + */ + def schemaFileLineColumnNumber: String + + def path: String + + /** + * The name of the schema component, in a form suitable for diagnostic messages. + * Unnamed components like sequence or choice groups have a diagnosticDebugName, despite not having + * any actual name. + * @return the name of the component, suitable for use in diagnostic messages. + */ + def diagnosticDebugName: String + + /** + * The standard conversion of the metadata component to a string. + * Unless overridden this uses the [[org.apache.daffodil.runtime1.api.Metadata.diagnosticDebugName]]. + * @return string representation of this metadata component. + */ + override def toString = diagnosticDebugName +} + +/* + * Provides metadata access that is common to all Terms, which include + * Elements of simple or complex type, as well as the Sequence and Choice groups. + */ +trait TermMetadata extends Metadata { + // nothing here +} + +/** + * Common metadata access for all elements, of simple or complex type. + */ +trait ElementMetadata extends TermMetadata { + + /** + * @return the name of this element. In the case of a global/qualified name, this is only the local + * part of the QName. + */ + def name: String + + /** + * @return the namespace URI as a string, or null if no namespace. + */ + def namespace: String + + /** + * @return the namespace bindings needed to construct an XML element from a Daffodil infoset + * element of simple or complex type. + */ + def minimizedScope: NamespaceBinding Review Comment: Everything one needs to synthesize XML as an output representation is needed, and this was one of the things. ########## daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/processors/MetadataWalker.scala: ########## @@ -0,0 +1,76 @@ +package org.apache.daffodil.runtime1.processors Review Comment: Ok, so this metadata walker is centralized in runtime1. SAPI/JAPI just have a walkMetadata method that takes a MetadataHandler. The runtime1/api/MetadataHandler class is perhaps the one to be concerned about. It has two methods that I don't like. Comments on that file. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
