001/*
002 * ModeShape (http://www.modeshape.org)
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *       http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.modeshape.schematic;
017
018import java.util.Objects;
019import org.modeshape.schematic.document.Binary;
020import org.modeshape.schematic.document.Document;
021import org.modeshape.schematic.internal.document.BasicDocument;
022
023/**
024 * A wrapper over a conventional {@link Document} which exposes a predefined structure of documents usually stored inside
025 * a {@link SchematicDb}.
026 * 
027 * @author Randall Hauch <rhauch@redhat.com> (C) 2011 Red Hat Inc.
028 * @author Horia Chiorean <hchiorea@redhat.com>
029 * 
030 * @since 5.0
031 */
032@FunctionalInterface
033public interface SchematicEntry {
034
035    abstract class FieldName {
036        private FieldName() {
037        }
038
039        /**
040         * The name of the field used internally to store an entry's metadata.
041         */
042        protected static final String  METADATA = "metadata";
043        
044        /**
045         * The name of the field used internally to store an entry's content, which is either a {@link Document} or a
046         * {@link Binary} value.
047         */
048        protected static final String CONTENT = "content";
049
050        /**
051         * The name of the metadata field used to store the document key. Note that {@value} is also the field name used by <a
052         * href="http://tools.ietf.org/html/draft-zyp-json-schema-03#section-5.27">JSON Schema</a>.
053         */
054        protected static final String ID = "id";
055    }
056
057    /**
058     * Returns the original document which is wrapped by this entry.
059     *
060     * @return a {@link Document} instance, never {@code null}
061     */
062    Document source();
063
064    /**
065     * Get the metadata associated with this document.
066     *
067     * @return the metadata document or null if there is no metadata document
068     */
069    default Document getMetadata() {
070        return source().getDocument(FieldName.METADATA);
071    }
072
073    /**
074     * Return this document's content. The result will either be a {@link Document} or null.
075     *
076     * @return the content, or null if there is no content
077     */
078    default Document content() {
079        return SchematicEntry.content(source());
080    }
081
082    /**
083     * Returns this document's id.
084     *
085     * @return the ID, or null if no ID field is present
086     * @throws NullPointerException if this document does not have a metadata section
087     */
088    default String id() {
089        return SchematicEntry.id(source());
090    }
091
092    /**
093     * Creates a new empty entry with the given id.
094     * 
095     * @param id the id of the document, may not be null. 
096     * @return a new {@link SchematicEntry}, never {@code null}
097     */
098    static SchematicEntry create(String id) {
099        return create(id, new BasicDocument());    
100    }
101
102    /**
103     * Creates a new entry with the given content.
104     *
105     * @param id the id of the document, may not be null.
106     * @param content the id of the document, may not be null.
107     * @return a new {@link SchematicEntry}, never {@code null}
108     */
109    static SchematicEntry create(String id, Document content) {
110        id = Objects.requireNonNull(id, "id cannot be null");
111        content = Objects.requireNonNull(content, "content cannot be null");
112        final Document source = new BasicDocument(FieldName.METADATA, new BasicDocument(FieldName.ID, id), 
113                                                  FieldName.CONTENT, content);
114        return () -> source;
115    }
116
117    /**
118     * Returns the value of the ID from a given entry document.
119     * 
120     * @param entryDocument a {@link Document} instance representing a schematic entry.
121     * @return a {@link String} or {@code null} if there is no {@link org.modeshape.schematic.SchematicEntry.FieldName#METADATA}
122     * document or if that document doesn't have an id.
123     */
124    static String id(Document entryDocument) {
125        Document metadata = entryDocument.getDocument(FieldName.METADATA);
126        if (metadata == null) {
127            return null;
128        }
129        return metadata.getString(FieldName.ID);
130    }
131
132    /**
133     * Returns the value of the CONTENT document from a given entry document.
134     * 
135     * @param entryDocument a {@link Document} instance representing a schematic entry.
136     * @return a {@link Document} or {@code null} if there is no {@link org.modeshape.schematic.SchematicEntry.FieldName#CONTENT}
137     * document.
138     */
139    static Document content(Document entryDocument) {
140        return entryDocument.getDocument(FieldName.CONTENT);
141    }
142    
143    /**
144     * Creates a new schematic entry instance based on the given document.
145     * 
146     * @param entryDocument a {@link Document} instance; may not be {@code null}
147     * @return a {@link SchematicEntry} instance which wraps the underlying document; never {@code null}
148     */
149    static SchematicEntry fromDocument(Document entryDocument) {
150        Objects.requireNonNull(entryDocument, "document cannot be null");
151        return () -> entryDocument;
152    }
153}