--- /dev/null
+/*
+ * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.opendaylight.yangtools.yang.common;
+
+import java.net.URI;
+
+/**
+ * Constant definitions present in RFC documents related to the YANG language.
+ */
+public final class YangConstants {
+ /**
+ * YANG namespace, as defined in RFC 6020.
+ */
+ public static final URI RFC6020_YANG_NAMESPACE = URI.create("urn:ietf:params:xml:ns:yang:1");
+
+ /**
+ * YIN namespace, as defined in RFC 6020.
+ */
+ public static final URI RFC6020_YIN_NAMESPACE = URI.create("urn:ietf:params:xml:ns:yang:yin:1");
+
+ /**
+ * Base QNameModule for all YANG statements.
+ */
+ public static final QNameModule RFC6020_YANG_MODULE = QNameModule.cachedReference(QNameModule.create(RFC6020_YANG_NAMESPACE, null));
+
+ /**
+ * Base QNameModule for all YIN statements.
+ */
+ public static final QNameModule RFC6020_YIN_MODULE = QNameModule.cachedReference(QNameModule.create(RFC6020_YIN_NAMESPACE, null));
+
+ private YangConstants() {
+ throw new UnsupportedOperationException("Utility class");
+ }
+
+}
--- /dev/null
+/*
+ * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.opendaylight.yangtools.yang.model.api.meta;
+
+import java.util.Collection;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+/**
+ * Represents declared statement
+ *
+ * @param <A> Argument type ({@link Void} if statement does not have argument.)
+ */
+public interface DeclaredStatement<A> extends ModelStatement<A> {
+
+ /**
+ *
+ * Returns statement argument as was present in original source.
+ *
+ * @return statement argument as was present in original source or null, if statement does not take argument.
+ */
+ @Nullable String rawArgument();
+
+ /**
+ *
+ * Returns collection of explicitly declared child statements, while preserving its original
+ * ordering from original source.
+ *
+ * @return Collection of statements, which were explicitly declared in
+ * source of model.
+ */
+ @Nonnull Collection<? extends DeclaredStatement<?>> declaredSubstatements();
+
+}
--- /dev/null
+/*
+ * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.opendaylight.yangtools.yang.model.api.meta;
+
+import java.util.Collection;
+import java.util.Map;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/**
+ * Effective model statement which should be used to derive application behaviour.
+ *
+ * @param <A>
+ * Argument type ({@link Void} if statement does not have argument.)
+ * @param <S>
+ * Class representing declared version of this statement.
+ */
+public interface EffectiveStatement<A, S extends DeclaredStatement<A>> extends ModelStatement<A> {
+
+ /**
+ * Returns statement, which was explicit declaration of this effective
+ * statement.
+ *
+ *
+ * @return statement, which was explicit declaration of this effective
+ * statement or null if statement was inferred from context.
+ */
+ @Nullable
+ S getDeclared();
+
+ /**
+ *
+ * Returns value associated with supplied identifier
+ *
+ * @param <K>
+ * Identifier type
+ * @param <V>
+ * Value type
+ * @param <N>
+ * Namespace identifier type
+ * @param namespace
+ * Namespace type
+ * @param identifier
+ * Identifier of element.
+ * @return Value if present, null otherwise.
+ *
+ *
+ */
+ @Nullable
+ <K, V, N extends IdentifierNamespace<? super K, ? extends V>> V get(@Nonnull Class<N> namespace,@Nonnull K identifier);
+
+ /**
+ *
+ * Returns all local values from supplied namespace.
+ *
+ * @param <K>
+ * Identifier type
+ * @param <V>
+ * Value type
+ * @param <N>
+ * Namespace identifier type
+ * @param namespace
+ * Namespace type
+ * @return Value if present, null otherwise.
+ */
+ @Nullable
+ <K, V, N extends IdentifierNamespace<K, V>> Map<K, V> getAll(@Nonnull Class<N> namespace);
+
+ /**
+ *
+ * Returns iteration of all effective substatements.
+ *
+ * @return iteration of all effective substatements.
+ */
+ Collection<? extends EffectiveStatement<?, ?>> effectiveSubstatements();
+
+}
--- /dev/null
+/*
+ * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.opendaylight.yangtools.yang.model.api.meta;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+/**
+ *
+ * Model specific namespace which allows access to specific
+ *
+ * {@link IdentifierNamespace} serves as common superclass for YANG model
+ * namespaces, which are type-captured subclasses. This type capture
+ * of namespace allows for handy type-safe reading methods
+ * such as {@link EffectiveStatement#get(Class, Object)} and still
+ * allows introduction of new namespaces without need to change
+ * model APIs.
+ *
+ * @param <K> Identifier type
+ * @param <V> Value type
+ */
+public interface IdentifierNamespace<K,V> {
+
+ /**
+ *
+ * Returns value associated with supplied identifier
+ *
+ * @param identifier Identifier of value
+ * @return value or null, if identifier is not present in namespace.
+ */
+ @Nullable V get(@Nonnull K identifier);
+
+}
--- /dev/null
+/*
+ * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.opendaylight.yangtools.yang.model.api.meta;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/**
+ *
+ * Model statement
+ *
+ * There are two base types of model statements:
+ * <ul>
+ * <li>{@link DeclaredStatement} - Statement representation as was defined in original
+ * source. This representation could be used during computation of effective model
+ * or during transforming YANG model from one serialization format to other.
+ * </li>
+ * <li>
+ * {@link EffectiveStatement} - Representation of effective statement - this
+ * statement may be different from declared, in such way, that it contains additional
+ * substatements, provides access to model namespaces. Some effective statements may be not
+ * directly declared in YANG source, but could be inferred by semantic processing of
+ * other statements (eg. uses, augment).
+ * </li>
+ * </ul>
+ *
+ * @param <A> Argument type ({@link Void} if statement does not have argument.)
+ */
+public interface ModelStatement<A> {
+
+ /**
+ * Statement Definition of this statement.
+ *
+ * @return definition of this statement.
+ */
+ @Nonnull StatementDefinition statementDefinition();
+
+ /**
+ *
+ * Returns statement argument
+ *
+ * @return statement argument or null if statement does not have argument.
+ */
+ @Nullable A argument();
+
+ /**
+ * Returns statement source, which denotes if statement was
+ * explicitly declared in original model or inferred during
+ * semantic processing of model.
+ *
+ * @return statement source.
+ */
+ @Nonnull StatementSource getStatementSource();
+
+}
--- /dev/null
+/*
+ * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.opendaylight.yangtools.yang.model.api.meta;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import org.opendaylight.yangtools.concepts.Immutable;
+import org.opendaylight.yangtools.yang.common.QName;
+
+/**
+ *
+ * Definition / model of YANG {@link DeclaredStatement} and {@link EffectiveStatement}.
+ *
+ * Statement concept is defined in RFC6020 section 6.3:
+ * <blockquote> A YANG
+ * module contains a sequence of statements. Each statement starts with a
+ * keyword, followed by zero or one argument
+ * </blockquote>
+ *
+ * Source: <a href="https://tools.ietf.org/html/rfc6020#section-6.3"> </a>
+ *
+ *
+ */
+public interface StatementDefinition extends Immutable {
+
+ /**
+ *
+ * Returns name of the statement
+ *
+ * @return Name of the statement
+ */
+ @Nonnull
+ QName getStatementName();
+
+ /**
+ *
+ * Returns name of statement argument or null, if statement does not have
+ * argument.
+ *
+ * @return argument name or null, if statement does not take argument.
+ */
+ @Nullable
+ QName getArgumentName();
+
+ /**
+ *
+ * Returns class which represents declared version of statement associated
+ * with this definition.
+ *
+ * This class should be interface, which provides convenience access to
+ * declared substatements.
+ *
+ * @return class which represents declared version of statement associated
+ * with this definition.
+ */
+ @Nonnull
+ Class<? extends DeclaredStatement<?>> getDeclaredRepresentationClass();
+
+ /**
+ *
+ * Returns class which represents supplied statement.
+ *
+ * This class should be interface, which defines convenience access to
+ * statement properties, namespace items and substatements.
+ *
+ * @return class which represents declared version of statement associated
+ * with this definition
+ */
+ @Nonnull
+ Class<? extends DeclaredStatement<?>> getEffectiveRepresentationClass();
+
+}
--- /dev/null
+/*
+ * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.opendaylight.yangtools.yang.model.api.meta;
+/**
+ *
+ * Origin of statement
+ *
+ * Represents origin of statement - if it was explicitly present
+ * in model representation or if it was inferred from context.
+ *
+ */
+public enum StatementSource {
+
+ /**
+ *
+ * Statement was explicitly declared by author
+ * of the supplied model.
+ *
+ */
+ DECLARATION,
+ /**
+ *
+ * Statement was derived from context of YANG model / statement
+ * and represents effective model.
+ *
+ * Effective context nodes are derived from applicable {@link #DECLARATION}
+ * statements by interpreting their semantic meaning in context
+ * of current statement.
+ *
+ */
+ CONTEXT
+
+}
--- /dev/null
+/*
+ * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+/**
+ * Meta model of YANG model as was defined in RFC6020 and extracted by analysis
+ * of YANG text.
+ *
+ * <p>
+ * Existence of meta-model allows for better evolution of YANG language as it evolves
+ * and allows for better support of different serializations of YANG model.
+ *
+ * <h2>Statements</h2>
+ * YANG source is defined as sequence of statement in
+ * <a href="https://tools.ietf.org/html/rfc6020#section-6.3">RFC6020, Section 6.3</a>.
+ * this model is also correct for YIN, which is XML serialisation of YANG source.
+ * <p>
+ * Statements are represented as instances / subclasses of {@link org.opendaylight.yangtools.yang.model.api.meta.ModelStatement}
+ * concept and its two subconcepts which are:
+ * <ul>
+ * <li>
+ * {@link org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement} - this contains navigable
+ * set of statements model as they was defined / present in original processed
+ * sources.
+ * </li>
+ * <li>{@link org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement} - navigable set of statements
+ * which represents effective model of parsed YANG sources, which is derived by rules
+ * present in YANG specification and/or was introduced in form of extensions.
+ * </li>
+ * </ul>
+ * <p>
+ * Clear separation of declared / effective model is needed, since statement definition also
+ * contains information how effective model is computed and there is no one to one mapping
+ * between declared and effective model thanks to statements such as {@code uses},
+ * {@code augment},{@code deviate},{@code refine}.
+ *
+ * <h2>Identifiers and Namespaces</h2>
+ * Effective model of YANG has several identifier types and namespaces, which behaves differently
+ * and are mostly used during processing data and/or during computing effective (semantic) model.
+ * <p>
+ * Common abstraction for various types of namespaces is {@link org.opendaylight.yangtools.yang.model.api.meta.IdentifierNamespace}
+ * from which concrete effective model namespaces are derived.
+ *
+ */
+package org.opendaylight.yangtools.yang.model.api.meta;
\ No newline at end of file
Code Review / yangtools.git / commitdiff