/* 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.
 */

parcel Lucy;

/** User-created specification for an inverted index.
 *
 * A Schema is a specification which indicates how other entities should
 * interpret the raw data in an inverted index and interact with it.
 *
 * Once an actual index has been created using a particular Schema, existing
 * field definitions may not be changed.  However, it is possible to add new
 * fields during subsequent indexing sessions.
 */
public class Lucy::Plan::Schema inherits Clownfish::Obj {

    Architecture      *arch;
    Similarity        *sim;
    Hash              *types;
    Hash              *sims;
    Hash              *analyzers;
    VArray            *uniq_analyzers;

    public inert incremented Schema*
    new();

    /** Constructor.  Takes no arguments.
     */
    public inert Schema*
    init(Schema *self);

    /** Factory method which creates an Architecture object for this index.
     */
    public incremented Architecture*
    Architecture(Schema *self);

    /** Define the behavior of a field by associating it with a FieldType.
     *
     * If this method has already been called for the supplied
     * <code>field</code>, it will merely test to verify that the supplied
     * FieldType Equals() the existing one.
     *
     * @param name The name of the field.
     * @param type A FieldType.
     */
    public void
    Spec_Field(Schema *self, const CharBuf *name, FieldType *type);

    /** Return the FieldType for the specified field.  If the field can't be
     * found, return NULL.
     */
    public nullable FieldType*
    Fetch_Type(Schema *self, const CharBuf *field);

    /** Return the Analyzer for the specified field.
     */
    nullable Analyzer*
    Fetch_Analyzer(Schema *self, const CharBuf *field = NULL);

    /** Return the Similarity for the specified field, or NULL if either the
     * field can't be found or it isn't associated with a Similarity.
     */
    public nullable Similarity*
    Fetch_Sim(Schema *self, const CharBuf *field = NULL);

    /** Return the number of fields currently defined.
     */
    public uint32_t
    Num_Fields(Schema *self);

    /** Return all the Schema's field names as an array.
     */
    public incremented VArray*
    All_Fields(Schema *self);

    /** Return the Schema instance's internal Architecture object.
     */
    public Architecture*
    Get_Architecture(Schema *self);

    /** Return the Schema instance's internal Similarity object.
     */
    public Similarity*
    Get_Similarity(Schema *self);

    public incremented Hash*
    Dump(Schema *self);

    public incremented Schema*
    Load(Schema *self, Obj *dump);

    /** Absorb the field definitions of another Schema, verify compatibility.
     */
    void
    Eat(Schema *self, Schema *other);

    void
    Write(Schema *self, Folder *folder, const CharBuf *filename = NULL);

    public void
    Destroy(Schema *self);
}