it.tidalwave.bluebill.taxonomy.Taxonomy Maven / Gradle / Ivy

Go to download
/***********************************************************************************************************************
 *
 * blueBill Core - open source birding
 * Copyright (C) 2009-2011 by Tidalwave s.a.s. (http://www.tidalwave.it)
 *
 ***********************************************************************************************************************
 *
 * Licensed 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.
 *
 ***********************************************************************************************************************
 *
 * WWW: http://bluebill.tidalwave.it
 * SCM: https://java.net/hg/bluebill~core-src
 *
 **********************************************************************************************************************/
package it.tidalwave.bluebill.taxonomy;

import javax.annotation.Nonnull;
import java.io.Serializable;
import org.openide.util.Lookup;
import it.tidalwave.util.As;
import it.tidalwave.role.spi.DefaultMutableDisplayable;
import it.tidalwave.role.Displayable;
import it.tidalwave.util.Id;
import it.tidalwave.util.Initializer;
import it.tidalwave.role.MutableDisplayable;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
import java.util.Locale;

/***********************************************************************************************************************
 *
 * This class models a hierarchical structure of {@link Taxon} instances. Every {@link Taxonomy} has a single
 * "top concept"; each concept has a name, an identifier and zero ore more child concepts.
 *
 * @navassoc - "" - Taxon.Builder
 * @composed "1" "" "0..n" Taxon
 * 
 * @author  Fabrizio Giudici
 * @version $Id$
 *
 **********************************************************************************************************************/
public interface Taxonomy extends Lookup.Provider, Displayable, Serializable, As
  {
    /*******************************************************************************************************************
     * 
     * A builder used to create new {@link Taxonomy} instances. This class implements
     * the Fluent Interface
     * pattern.
     * 
     * @navassoc - "" - Taxonomy
     * 
     ******************************************************************************************************************/
    public abstract class Builder
      {
        protected Displayable displayable = new DefaultMutableDisplayable("", "");

        protected Id id;

        protected Object repository;

        protected final List> initializers = new ArrayList>();

        protected Builder()
          {
          }

        @Nonnull
        public Builder withDisplayName (final @Nonnull String displayName, final @Nonnull Locale locale)
          {
            ((MutableDisplayable)displayable).setDisplayName(displayName, locale);
            return this;
          }

        @Nonnull
        public Builder withDisplayNames (final @Nonnull Displayable displayable)
          {
            this.displayable = displayable;
            return this;
          }

        @Nonnull
        public Builder withId (final @Nonnull Id id)
          {
            this.id = id;
            return this;
          }

        @Nonnull
        public Builder inRepository (final @Nonnull Object repository)
          {
            this.repository = repository;
            return this;
          }

        @Nonnull
        public Builder withInitializer (final @Nonnull Initializer initializer)
          {
            initializers.add(initializer);
            return this;
          }

        @Nonnull
        public Builder withInitializers (final @Nonnull Collection> initializers)
          {
            this.initializers.addAll(initializers);
            return this;
          }

        @Nonnull
        public Displayable getDisplayable()
          {
            return displayable;
          }

        public Id getId()
          {
            return id;
          }

        @Nonnull
        public List> getInitializers()
          {
            return initializers;
          }

        public Object getRank()
          {
            return repository;
          }

        @Nonnull
        public abstract Taxonomy build();
      }

    /*******************************************************************************************************************
     *
     * Creates a top taxon for this {@code Taxonomy}.
     *
     ******************************************************************************************************************/
    @Nonnull
    public Taxon.Builder createTopTaxon();

    /*******************************************************************************************************************
     *
     * TBD
     *
     *
     ******************************************************************************************************************/
    @Nonnull
    public Taxon.Builder createTaxon();

    /*******************************************************************************************************************
     *
     * Returns the top concept of this {@code Taxonomy}.
     *
     * @return  the top concept
     *
     ******************************************************************************************************************/
    @Nonnull
    public Taxon getTopTaxon();

    /*******************************************************************************************************************
     *
     * Returns a {@link Finder} for performing queries.
     *
     * @return  the {@code Finder}
     *
     ******************************************************************************************************************/
    @Nonnull
    public Finder findTaxa();

    /*******************************************************************************************************************
     *
     * Finds or create an {@link AnonymousTaxon} with a given id.
     * FIXME: drop this
     *
     * @param   id  the id
     * @return  the {@code AnonymousTaxon}
     *
     ******************************************************************************************************************/
    @Nonnull
    public Taxon findOrCreateAnonymousTaxon (@Nonnull String id);
  }