it.tidalwave.bluebill.taxonomy.Taxon 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.util.ArrayList;
import java.util.Collection;
import java.util.List;
import java.util.Locale;
import it.tidalwave.util.As;
import it.tidalwave.util.Id;
import it.tidalwave.util.Initializer;
import it.tidalwave.util.NotFoundException;
import it.tidalwave.role.LocalizedDisplayable;
import it.tidalwave.role.MutableDisplayable;
import it.tidalwave.role.spi.DefaultMutableDisplayable;
import org.openide.util.Lookup;
import lombok.ToString;

/***********************************************************************************************************************
 *
 * Represents an element in a {@link Taxonomy}.
 * 
 * @author  Fabrizio Giudici
 * @version $Id$
 *
 * @stereotype Datum
 * @navassoc - "" - Taxon.Builder
 * @composed "1" "" "0..n" Taxon
 * 
 **********************************************************************************************************************/
public interface Taxon extends LocalizedDisplayable, Lookup.Provider, As
  {
    public static final Class Taxon = Taxon.class;
    
    /*******************************************************************************************************************
     *
     * A builder used to create new {@link Taxon} instances. This class implements
     * the Fluent Interface
     * pattern.
     *
     * @navassoc - "" - Taxon
     *
     ******************************************************************************************************************/
    @ToString
    public abstract class Builder
      {
        protected LocalizedDisplayable displayable = new DefaultMutableDisplayable("", "");

        protected Id id;

        protected Id scientificNameId;

        protected String scientificName;

        protected String specificEpythet;

        protected Rank rank;

        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 LocalizedDisplayable displayable)
          {
            this.displayable = displayable;
            return this;
          }

        @Nonnull
        public Builder withScientificName (final @Nonnull String scientificName)
          {
            this.scientificName = scientificName;
            return this;
          }

        @Nonnull
        public Builder withSpecificEpythet (final @Nonnull String specificEpythet)
          {
            this.specificEpythet = specificEpythet;
            return this;
          }

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

        @Nonnull
        public Builder withScientificNameId (final @Nonnull Id scientificNameId)
          {
            this.scientificNameId = scientificNameId;
            return this;
          }

        @Nonnull
        public Builder withRank (final @Nonnull Rank rank)
          {
            this.rank = rank;
            return this;
          }

        @Nonnull
        public abstract Taxon build();

        @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 LocalizedDisplayable getDisplayable()
          {
            return displayable;
          }

        public Id getId()
          {
            return id;
          }

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

        public Rank getRank()
          {
            return rank;
          }

        public String getScientificName()
          {
            return scientificName;
          }

        public Id getScientificNameId()
          {
            return scientificNameId;
          }

        public String getSpecificEpythet()
          {
            return specificEpythet;
          }
      }

    /*******************************************************************************************************************
     *
     * Represents the rank of a {@link Taxon}.
     *
     ******************************************************************************************************************/
    public enum Rank
      {
        CLASS,
        ORDER,
        FAMILY,
        SUBFAMILY,
        GENUS,
        SPECIES,
        SUBSPECIES
      }
    
    /*******************************************************************************************************************
     *
     * Creates a sub {@link Taxon}.
     *
     * @return              the sub {@code Taxon}
     *
     ******************************************************************************************************************/
    @Nonnull
    public Builder createSubTaxon();

    /*******************************************************************************************************************
     *
     * Finds the sub taxa of this object.
     *
     * @return  a {@link Finder} of sub concepts
     *
     ******************************************************************************************************************/
    @Nonnull
    public Finder findSubTaxa();

    @Nonnull
    public Id getScientificNameId()
      throws NotFoundException;

    public String getScientificName(); // FIXME  throws NotFoundException;

    public String getSpecificEpithet();// FIXME  throws NotFoundException;

    /*******************************************************************************************************************
     *
     * Return the {@link AnonymousTaxon} which is synonym to this object.
     *
     * @return  the synonym
     * @throws  NotFoundException  if no synonym
     *
     ******************************************************************************************************************/
    @Nonnull
//    public AnonymousTaxon getAnonymousSynonym()
    public Taxon getAnonymousSynonym()
      throws NotFoundException;

    @Nonnull
    public Finder findSynonyms();
  }