EDIT

/**

 * Copyright (C) 2007 EDIT

 * European Distributed Institute of Taxonomy 

 * http://www.e-taxonomy.eu

 * 

 * The contents of this file are subject to the Mozilla Public License Version 1.1

 * See LICENSE.TXT at the top of this package for the full license terms.

 */

package eu.etaxonomy.cdm.api.facade;

import java.beans.PropertyChangeEvent;

import java.beans.PropertyChangeListener;

import java.text.ParseException;

import java.util.ArrayList;

import java.util.HashMap;

import java.util.HashSet;

import java.util.List;

import java.util.Map;

import java.util.Set;

import javax.persistence.Transient;

import org.apache.commons.lang.StringUtils;

import org.apache.log4j.Logger;

import eu.etaxonomy.cdm.api.service.IOccurrenceService;

import eu.etaxonomy.cdm.common.CdmUtils;

import eu.etaxonomy.cdm.common.UTF8;

import eu.etaxonomy.cdm.model.agent.AgentBase;

import eu.etaxonomy.cdm.model.agent.Person;

import eu.etaxonomy.cdm.model.common.Annotation;

import eu.etaxonomy.cdm.model.common.CdmBase;

import eu.etaxonomy.cdm.model.common.DefinedTerm;

import eu.etaxonomy.cdm.model.common.IOriginalSource;

import eu.etaxonomy.cdm.model.common.IdentifiableSource;

import eu.etaxonomy.cdm.model.common.Language;

import eu.etaxonomy.cdm.model.common.LanguageString;

import eu.etaxonomy.cdm.model.common.OriginalSourceType;

import eu.etaxonomy.cdm.model.common.TimePeriod;

import eu.etaxonomy.cdm.model.description.DescriptionElementBase;

import eu.etaxonomy.cdm.model.description.Feature;

import eu.etaxonomy.cdm.model.description.SpecimenDescription;

import eu.etaxonomy.cdm.model.description.TextData;

import eu.etaxonomy.cdm.model.location.NamedArea;

import eu.etaxonomy.cdm.model.location.Point;

import eu.etaxonomy.cdm.model.location.ReferenceSystem;

import eu.etaxonomy.cdm.model.media.Media;

import eu.etaxonomy.cdm.model.name.TaxonNameBase;

import eu.etaxonomy.cdm.model.occurrence.Collection;

import eu.etaxonomy.cdm.model.occurrence.DerivationEvent;

import eu.etaxonomy.cdm.model.occurrence.DerivationEventType;

import eu.etaxonomy.cdm.model.occurrence.DerivedUnit;

import eu.etaxonomy.cdm.model.occurrence.DerivedUnitBase;

import eu.etaxonomy.cdm.model.occurrence.DeterminationEvent;

import eu.etaxonomy.cdm.model.occurrence.FieldObservation;

import eu.etaxonomy.cdm.model.occurrence.GatheringEvent;

import eu.etaxonomy.cdm.model.occurrence.PreservationMethod;

import eu.etaxonomy.cdm.model.occurrence.Specimen;

import eu.etaxonomy.cdm.model.occurrence.SpecimenOrObservationBase;

import eu.etaxonomy.cdm.model.reference.Reference;

/**

 * This class is a facade to the eu.etaxonomy.cdm.model.occurrence package from

 * a specimen based view. It does not support all functionality available in the

 * occurrence package.<BR>

 * The most significant restriction is that a specimen may derive only from one

 * direct derivation event and there must be only one field observation

 * (gathering event) it derives from.<BR>

 * 

 * @author a.mueller

 * @date 14.05.2010

 */

public class DerivedUnitFacade {

	@SuppressWarnings("unused")

	private static final Logger logger = Logger.getLogger(DerivedUnitFacade.class);

	private static final String notSupportMessage = "A specimen facade not supported exception has occurred at a place where this should not have happened. The developer should implement not support check properly during class initialization ";

	private static final boolean CREATE = true;

	private static final boolean CREATE_NOT = false;

	/**

	 * Enum that defines the class the "Specimen" belongs to. Some methods of

	 * the facade are not available for certain classes and will throw an

	 * Exception when invoking them.

	 */

	public enum DerivedUnitType {

		Specimen("Specimen"), 

		Observation("Observation"), 

		LivingBeing("Living Being"), 

		Fossil("Fossil"), 

		DerivedUnit("Derived Unit"),

		//Field Observation is experimental, please handle with care (it is the only type which does not

		//have a derivedUnit and therefore throws exceptions for all method on derivedUnit attributes

		FieldObservation("FieldObservation");

		String representation;

		private DerivedUnitType(String representation) {

			this.representation = representation;

		}

		/**

		 * @return the representation

		 */

		public String getRepresentation() {

			return representation;

		}

		public DerivedUnitBase<?> getNewDerivedUnitInstance() {

			if (this == DerivedUnitType.Specimen) {

				return eu.etaxonomy.cdm.model.occurrence.Specimen.NewInstance();

			} else if (this == DerivedUnitType.Observation) {

				return eu.etaxonomy.cdm.model.occurrence.Observation.NewInstance();

			} else if (this == DerivedUnitType.LivingBeing) {

				return eu.etaxonomy.cdm.model.occurrence.LivingBeing.NewInstance();

			} else if (this == DerivedUnitType.Fossil) {

				return eu.etaxonomy.cdm.model.occurrence.Fossil.NewInstance();

			} else if (this == DerivedUnitType.DerivedUnit) {

				return eu.etaxonomy.cdm.model.occurrence.DerivedUnit.NewInstance();

			} else if (this == DerivedUnitType.FieldObservation) {

				return null;

			} else {

				String message = "Unknown derived unit type %s";

				message = String.format(message, this.getRepresentation());

				throw new IllegalStateException(message);

			}

		}

		public static DerivedUnitType valueOf2(String type) {

			if (type == null) {

				return null;

			}

			type = type.replace(" ", "").toLowerCase();

			if (type.equals("specimen")) {

				return Specimen;

			} else if (type.equals("livingbeing")) {

				return LivingBeing;

			} else if (type.equals("observation")) {

				return Observation;

			} else if (type.equals("fossil")) {

				return Fossil;

			} else if (type.equals("fieldobservation")) {

				return DerivedUnitType.FieldObservation;

			} else if (type.equals("unknown")) {

				return DerivedUnitType.DerivedUnit;

			} else if (type.equals("derivedunit")) {

				return DerivedUnitType.DerivedUnit;

			}

			return null;

		}

		public static DerivedUnitType valueOf2(Class<? extends SpecimenOrObservationBase> clazz) {

			if (clazz == null) {

				return null;

			}

			if (clazz.equals(Specimen.class)) {

				return Specimen;

			} else if (clazz.equals(eu.etaxonomy.cdm.model.occurrence.LivingBeing.class)) {

				return LivingBeing;

			} else if (clazz.equals(eu.etaxonomy.cdm.model.occurrence.Observation.class)) {

				return Observation;

			} else if (clazz.equals(eu.etaxonomy.cdm.model.occurrence.Fossil.class)) {

				return Fossil;

			} else if (clazz.equals(FieldObservation.class)) {

				return DerivedUnitType.FieldObservation;

			} else if (clazz.equals(DerivedUnit.class)) {

				return DerivedUnitType.DerivedUnit;

			}

			return null;

		}

	}

	private final DerivedUnitFacadeConfigurator config;

	private Map<PropertyChangeListener, CdmBase> listeners = new HashMap<PropertyChangeListener, CdmBase>();

	// private GatheringEvent gatheringEvent;

	private DerivedUnitType type; // needed?

	private FieldObservation fieldObservation;

	private final DerivedUnitBase derivedUnit;

	// media - the text data holding the media

	private TextData derivedUnitMediaTextData;

	private TextData fieldObjectMediaTextData;

	private TextData ecology;

	private TextData plantDescription;

	/**

	 * Creates a derived unit facade for a new derived unit of type

	 * <code>type</code>.

	 * 

	 * @param type

	 * @return

	 */

	public static DerivedUnitFacade NewInstance(DerivedUnitType type) {

		return new DerivedUnitFacade(type, null, null);

	}

	/**

	 * Creates a derived unit facade for a new derived unit of type

	 * <code>type</code>.

	 * 

	 * @param type

	 * @return

	 */

	public static DerivedUnitFacade NewInstance(DerivedUnitType type, FieldObservation fieldObservation) {

		return new DerivedUnitFacade(type, fieldObservation, null);

	}

	/**

	 * Creates a derived unit facade for a new derived unit of type

	 * <code>type</code>.

	 * 

	 * @param type

	 * @param fieldObservation the field observation to use

	 * @param config the facade configurator to use

	 * //TODO are there any ambiguities to solve with defining a field observation or a configurator 

	 * @return

	 */

	public static DerivedUnitFacade NewInstance(DerivedUnitType type, FieldObservation fieldObservation, DerivedUnitFacadeConfigurator config) {

		return new DerivedUnitFacade(type, fieldObservation, config);

	}

	/**

	 * Creates a derived unit facade for a given derived unit using the default

	 * configuration.

	 * 

	 * @param derivedUnit

	 * @return

	 * @throws DerivedUnitFacadeNotSupportedException

	 */

	public static DerivedUnitFacade NewInstance(DerivedUnitBase derivedUnit)

			throws DerivedUnitFacadeNotSupportedException {

		return new DerivedUnitFacade(derivedUnit, null);

	}

	public static DerivedUnitFacade NewInstance(DerivedUnitBase derivedUnit,

			DerivedUnitFacadeConfigurator config)

			throws DerivedUnitFacadeNotSupportedException {

		return new DerivedUnitFacade(derivedUnit, config);

	}

	// ****************** CONSTRUCTOR ******************************************

	private DerivedUnitFacade(DerivedUnitType type, FieldObservation fieldObservation, DerivedUnitFacadeConfigurator config) {

		if (config == null){

			config = DerivedUnitFacadeConfigurator.NewInstance();

		}

		this.config = config;

		this.type = type;

		// derivedUnit

		derivedUnit = type.getNewDerivedUnitInstance();

		setFieldObservation(fieldObservation);

		if (derivedUnit != null){

			setCacheStrategy();

		}else{

			setFieldObservationCacheStrategy();

		}

	}

	private DerivedUnitFacade(DerivedUnitBase derivedUnit,

			DerivedUnitFacadeConfigurator config)

			throws DerivedUnitFacadeNotSupportedException {

		if (config == null) {

			config = DerivedUnitFacadeConfigurator.NewInstance();

		}

		this.config = config;

		// derived unit

		this.derivedUnit = derivedUnit;

		this.type = DerivedUnitType.valueOf2(this.derivedUnit.getClass());

		// derivation event

		if (this.derivedUnit.getDerivedFrom() != null) {

			DerivationEvent derivationEvent = getDerivationEvent(CREATE);

			// fieldObservation

			Set<FieldObservation> fieldOriginals = getFieldObservationsOriginals(

					derivationEvent, null);

			if (fieldOriginals.size() > 1) {

				throw new DerivedUnitFacadeNotSupportedException(

						"Specimen must not have more than 1 derivation event");

			} else if (fieldOriginals.size() == 0) {

				// fieldObservation = FieldObservation.NewInstance();

			} else if (fieldOriginals.size() == 1) {

				fieldObservation = fieldOriginals.iterator().next();

				// ###fieldObservation =

				// getInitializedFieldObservation(fieldObservation);

				if (config.isFirePropertyChangeEvents()){

					addNewEventPropagationListener(fieldObservation);

				}

			} else {

				throw new IllegalStateException("Illegal state");

			}

		}

		this.derivedUnitMediaTextData = inititializeTextDataWithSupportTest(

				Feature.IMAGE(), this.derivedUnit, false, true);

		fieldObjectMediaTextData = initializeFieldObjectTextDataWithSupportTest(

				Feature.IMAGE(), false, true);

		// handle derivedUnit.getMedia()

		if (derivedUnit.getMedia().size() > 0) {

			// TODO better changed model here to allow only one place for images

			if (this.config.isMoveDerivedUnitMediaToGallery()) {

				Set<Media> mediaSet = derivedUnit.getMedia();

				for (Media media : mediaSet) {

					this.addDerivedUnitMedia(media);

				}

				mediaSet.removeAll(getDerivedUnitMedia());

			} else {

				throw new DerivedUnitFacadeNotSupportedException(

						"Specimen may not have direct media. Only (one) image gallery is allowed");

			}

		}

		// handle fieldObservation.getMedia()

		if (fieldObservation != null && fieldObservation.getMedia() != null

				&& fieldObservation.getMedia().size() > 0) {

			// TODO better changed model here to allow only one place for images

			if (this.config.isMoveFieldObjectMediaToGallery()) {

				Set<Media> mediaSet = fieldObservation.getMedia();

				for (Media media : mediaSet) {

					this.addFieldObjectMedia(media);

				}

				mediaSet.removeAll(getFieldObjectMedia());

			} else {

				throw new DerivedUnitFacadeNotSupportedException(

						"Field object may not have direct media. Only (one) image gallery is allowed");

			}

		}

		// test if descriptions are supported

		ecology = initializeFieldObjectTextDataWithSupportTest(

				Feature.ECOLOGY(), false, false);

		plantDescription = initializeFieldObjectTextDataWithSupportTest(

				Feature.DESCRIPTION(), false, false);

		setCacheStrategy();

	}

	private DerivedUnitBase getInitializedDerivedUnit(

			DerivedUnitBase derivedUnit) {

		IOccurrenceService occurrenceService = this.config

				.getOccurrenceService();

		if (occurrenceService == null) {

			return derivedUnit;

		}

		List<String> propertyPaths = this.config.getPropertyPaths();

		if (propertyPaths == null) {

			return derivedUnit;

		}

		propertyPaths = getDerivedUnitPropertyPaths(propertyPaths);

		DerivedUnitBase result = (DerivedUnitBase) occurrenceService.load(

				derivedUnit.getUuid(), propertyPaths);

		return result;

	}

	/**

	 * Initializes the derived unit according to the configuartions property

	 * path. If the property path is <code>null</code> or no occurrence service

	 * is given the returned object is the same as the input parameter.

	 * 

	 * @param fieldObservation2

	 * @return

	 */

	private FieldObservation getInitializedFieldObservation(

			FieldObservation fieldObservation) {

		IOccurrenceService occurrenceService = this.config

				.getOccurrenceService();

		if (occurrenceService == null) {

			return fieldObservation;

		}

		List<String> propertyPaths = this.config.getPropertyPaths();

		if (propertyPaths == null) {

			return fieldObservation;

		}

		propertyPaths = getFieldObjectPropertyPaths(propertyPaths);

		FieldObservation result = (FieldObservation) occurrenceService.load(

				fieldObservation.getUuid(), propertyPaths);

		return result;

	}

	/**

	 * Transforms the property paths in a way that the facade is handled just

	 * like an ordinary CdmBase object.<BR>

	 * E.g. a property path "collectinAreas" will be translated into

	 * gatheringEvent.collectingAreas

	 * 

	 * @param propertyPaths

	 * @return

	 */

	private List<String> getFieldObjectPropertyPaths(List<String> propertyPaths) {

		List<String> result = new ArrayList<String>();

		for (String facadePath : propertyPaths) {

			// collecting areas (named area)

			if (facadePath.startsWith("collectingAreas")) {

				facadePath = "gatheringEvent." + facadePath;

				result.add(facadePath);

			}

			// collector (agentBase)

			else if (facadePath.startsWith("collector")) {

				facadePath = facadePath.replace("collector",

						"gatheringEvent.actor");

				result.add(facadePath);

			}

			// exactLocation (agentBase)

			else if (facadePath.startsWith("exactLocation")) {

				facadePath = "gatheringEvent." + facadePath;

				result.add(facadePath);

			}

			// gatheringPeriod (TimePeriod)

			else if (facadePath.startsWith("gatheringPeriod")) {

				facadePath = facadePath.replace("gatheringPeriod",

						"gatheringEvent.timeperiod");

				result.add(facadePath);

			}

			// (locality/ localityLanguage , LanguageString)

			else if (facadePath.startsWith("locality")) {

				facadePath = "gatheringEvent." + facadePath;

				result.add(facadePath);

			}

			// *********** FIELD OBJECT ************

			// fieldObjectDefinitions (Map<language, languageString)

			else if (facadePath.startsWith("fieldObjectDefinitions")) {

				// TODO or definition ???

				facadePath = facadePath.replace("fieldObjectDefinitions",

						"description");

				result.add(facadePath);

			}

			// fieldObjectMedia (Media)

			else if (facadePath.startsWith("fieldObjectMedia")) {

				// TODO ???

				facadePath = facadePath.replace("fieldObjectMedia",

						"descriptions.elements.media");

				result.add(facadePath);

			}

			// Gathering Event will always be added

			result.add("gatheringEvent");

		}

		/*

		 * Gathering Event ==================== - gatheringEvent

		 * (GatheringEvent)

		 * 

		 * Field Object ================= - ecology/ ecologyAll (String) ??? -

		 * plant description (like ecology)

		 * 

		 * - fieldObjectImageGallery (SpecimenDescription) - is automatically

		 * initialized via fieldObjectMedia

		 */

		return result;

	}

	/**

	 * Transforms the property paths in a way that the facade is handled just

	 * like an ordinary CdmBase object.<BR>

	 * E.g. a property path "collectinAreas" will be translated into

	 * gatheringEvent.collectingAreas

	 * 

	 * Not needed (?) as the facade works with REST service property paths

	 * without using this method.

	 * 

	 * @param propertyPaths

	 * @return

	 */

	private List<String> getDerivedUnitPropertyPaths(List<String> propertyPaths) {

		List<String> result = new ArrayList<String>();

		for (String facadePath : propertyPaths) {

			// determinations (DeterminationEvent)

			if (facadePath.startsWith("determinations")) {

				facadePath = "" + facadePath; // no change

				result.add(facadePath);

			}

			// storedUnder (TaxonNameBase)

			else if (facadePath.startsWith("storedUnder")) {

				facadePath = "" + facadePath; // no change

				result.add(facadePath);

			}

			// sources (IdentifiableSource)

			else if (facadePath.startsWith("sources")) {

				facadePath = "" + facadePath; // no change

				result.add(facadePath);

			}

			// collection (Collection)

			else if (facadePath.startsWith("collection")) {

				facadePath = "" + facadePath; // no change

				result.add(facadePath);

			}

			// (locality/ localityLanguage , LanguageString)

			else if (facadePath.startsWith("locality")) {

				facadePath = "gatheringEvent." + facadePath;

				result.add(facadePath);

			}

			// *********** FIELD OBJECT ************

			// derivedUnitDefinitions (Map<language, languageString)

			else if (facadePath.startsWith("derivedUnitDefinitions")) {

				// TODO or definition ???

				facadePath = facadePath.replace("derivedUnitDefinitions",

						"description");

				result.add(facadePath);

			}

			// derivedUnitMedia (Media)

			else if (facadePath.startsWith("derivedUnitMedia")) {

				// TODO ???

				facadePath = facadePath.replace("derivedUnitMedia",

						"descriptions.elements.media");

				result.add(facadePath);

			}

		}

		/*

		 * //TODO Derived Unit =====================

		 * 

		 * - derivedUnitImageGallery (SpecimenDescription) - is automatically

		 * initialized via derivedUnitMedia

		 * 

		 * - derivationEvent (DerivationEvent) - will always be initialized -

		 * duplicates (??? Specimen???) ???

		 */

		return result;

	}

	/**

	 * 

	 */

	private void setCacheStrategy() {

		if (derivedUnit == null) {

			throw new NullPointerException(

					"Facade's derviedUnit must not be null to set cache strategy");

		}else{

			derivedUnit.setCacheStrategy(new DerivedUnitFacadeCacheStrategy());

			setFieldObservationCacheStrategy();

		}

	}

	private void setFieldObservationCacheStrategy() {

		if (this.hasFieldObject()){

			DerivedUnitFacadeFieldObservationCacheStrategy strategy = new DerivedUnitFacadeFieldObservationCacheStrategy();

			this.fieldObservation.setCacheStrategy(strategy);

		}

	}

	/**

	 * @param feature

	 * @param createIfNotExists

	 * @param isImageGallery

	 * @return

	 * @throws DerivedUnitFacadeNotSupportedException

	 */

	private TextData initializeFieldObjectTextDataWithSupportTest(

			Feature feature, boolean createIfNotExists, boolean isImageGallery)

			throws DerivedUnitFacadeNotSupportedException {

		// field object

		FieldObservation fieldObject = getFieldObservation(createIfNotExists);

		if (fieldObject == null) {

			return null;

		}

		return inititializeTextDataWithSupportTest(feature, fieldObject,

				createIfNotExists, isImageGallery);

	}

	/**

	 * @param feature

	 * @param specimen

	 * @param createIfNotExists

	 * @param isImageGallery

	 * @return

	 * @throws DerivedUnitFacadeNotSupportedException

	 */

	private TextData inititializeTextDataWithSupportTest(Feature feature,

			SpecimenOrObservationBase specimen, boolean createIfNotExists,

			boolean isImageGallery)

			throws DerivedUnitFacadeNotSupportedException {

		if (feature == null) {

			return null;

		}

		TextData textData = null;

		if (createIfNotExists) {

			textData = TextData.NewInstance(feature);

		}

		Set<SpecimenDescription> descriptions;

		if (isImageGallery) {

			descriptions = specimen.getSpecimenDescriptionImageGallery();

		} else {

			descriptions = specimen.getSpecimenDescriptions(false);

		}

		// no description exists yet for this specimen

		if (descriptions.size() == 0) {

			if (createIfNotExists) {

				SpecimenDescription newSpecimenDescription = SpecimenDescription

						.NewInstance(specimen);

				newSpecimenDescription.addElement(textData);

				newSpecimenDescription.setImageGallery(isImageGallery);

				return textData;

			} else {

				return null;

			}

		}

		// description already exists

		Set<DescriptionElementBase> existingTextData = new HashSet<DescriptionElementBase>();

		for (SpecimenDescription description : descriptions) {

			// collect all existing text data

			for (DescriptionElementBase element : description.getElements()) {

				if (element.isInstanceOf(TextData.class)

						&& (feature.equals(element.getFeature()) || isImageGallery)) {

					existingTextData.add(element);

				}

			}

		}

		// use existing text data if exactly one exists

		if (existingTextData.size() > 1) {

			throw new DerivedUnitFacadeNotSupportedException(

					"Specimen facade does not support more than one description text data of type "

							+ feature.getLabel());

		} else if (existingTextData.size() == 1) {

			return CdmBase.deproxy(existingTextData.iterator().next(),

					TextData.class);

		} else {

			if (createIfNotExists) {

				SpecimenDescription description = descriptions.iterator()

						.next();

				description.addElement(textData);

			}

			return textData;

		}

	}

	/**

	 * Tests if a given image gallery is supported by the derived unit facade.

	 * It returns the only text data attached to the given image gallery. If the

	 * given image gallery does not have text data attached, it is created and

	 * attached.

	 * 

	 * @param imageGallery

	 * @return

	 * @throws DerivedUnitFacadeNotSupportedException

	 */

	private TextData testImageGallery(SpecimenDescription imageGallery)

			throws DerivedUnitFacadeNotSupportedException {

		if (imageGallery.isImageGallery() == false) {

			throw new DerivedUnitFacadeNotSupportedException(

					"Image gallery needs to have image gallery flag set");

		}

		if (imageGallery.getElements().size() > 1) {

			throw new DerivedUnitFacadeNotSupportedException(

					"Image gallery must not have more then one description element");

		}

		TextData textData;

		if (imageGallery.getElements().size() == 0) {

			textData = TextData.NewInstance(Feature.IMAGE());

			imageGallery.addElement(textData);

		} else {

			if (!imageGallery.getElements().iterator().next()

					.isInstanceOf(TextData.class)) {

				throw new DerivedUnitFacadeNotSupportedException(

						"Image gallery must only have TextData as element");

			} else {

				textData = CdmBase.deproxy(imageGallery.getElements()

						.iterator().next(), TextData.class);

			}

		}

		return textData;

	}

	// ************************** METHODS

	// *****************************************

	private TextData getDerivedUnitImageGalleryTextData(

			boolean createIfNotExists)

			throws DerivedUnitFacadeNotSupportedException {

		if (this.derivedUnitMediaTextData == null && createIfNotExists) {

			this.derivedUnitMediaTextData = getImageGalleryTextData(

					derivedUnit, "Specimen");

		}

		return this.derivedUnitMediaTextData;

	}

	private TextData getObservationImageGalleryTextData(

			boolean createIfNotExists)

			throws DerivedUnitFacadeNotSupportedException {

		if (this.fieldObjectMediaTextData == null && createIfNotExists) {

			this.fieldObjectMediaTextData = getImageGalleryTextData(

					fieldObservation, "Field observation");

		}

		return this.fieldObjectMediaTextData;

	}

	/**

	 * @param derivationEvent

	 * @return

	 * @throws DerivedUnitFacadeNotSupportedException

	 */

	private Set<FieldObservation> getFieldObservationsOriginals(

			DerivationEvent derivationEvent,

			Set<SpecimenOrObservationBase> recursionAvoidSet)

			throws DerivedUnitFacadeNotSupportedException {

		if (recursionAvoidSet == null) {

			recursionAvoidSet = new HashSet<SpecimenOrObservationBase>();

		}

		Set<FieldObservation> result = new HashSet<FieldObservation>();

		Set<SpecimenOrObservationBase> originals = derivationEvent.getOriginals();

		for (SpecimenOrObservationBase original : originals) {

			if (original.isInstanceOf(FieldObservation.class)) {

				result.add(CdmBase.deproxy(original, FieldObservation.class));

			} else if (original.isInstanceOf(DerivedUnitBase.class)) {

				// if specimen has already been tested exclude it from further

				// recursion

				if (recursionAvoidSet.contains(original)) {

					continue;

				}

				DerivedUnitBase derivedUnit = CdmBase.deproxy(original,

						DerivedUnitBase.class);

				DerivationEvent originalDerivation = derivedUnit.getDerivedFrom();

				// Set<DerivationEvent> derivationEvents =

				// original.getDerivationEvents();

				// for (DerivationEvent originalDerivation : derivationEvents){

				Set<FieldObservation> fieldObservations = getFieldObservationsOriginals(

						originalDerivation, recursionAvoidSet);

				result.addAll(fieldObservations);

				// }

			} else {

				throw new DerivedUnitFacadeNotSupportedException(

						"Unhandled specimen or observation base type: "

								+ original.getClass().getName());

			}

		}

		return result;

	}

	// *********** MEDIA METHODS ******************************

	// /**

	// * Returns the media list for a specimen. Throws an exception if the

	// existing specimen descriptions

	// * are not supported by this facade.

	// * @param specimen the specimen the media belongs to

	// * @param specimenExceptionText text describing the specimen for exception

	// messages

	// * @return

	// * @throws DerivedUnitFacadeNotSupportedException

	// */

	// private List<Media> getImageGalleryMedia(SpecimenOrObservationBase

	// specimen, String specimenExceptionText) throws

	// DerivedUnitFacadeNotSupportedException{

	// List<Media> result;

	// SpecimenDescription imageGallery =

	// getImageGalleryWithSupportTest(specimen, specimenExceptionText, true);

	// TextData textData = getImageTextDataWithSupportTest(imageGallery,

	// specimenExceptionText);

	// result = textData.getMedia();

	// return result;

	// }

	/**

	 * Returns the media list for a specimen. Throws an exception if the

	 * existing specimen descriptions are not supported by this facade.

	 * 

	 * @param specimen

	 *            the specimen the media belongs to

	 * @param specimenExceptionText

	 *            text describing the specimen for exception messages

	 * @return

	 * @throws DerivedUnitFacadeNotSupportedException

	 */

	private TextData getImageGalleryTextData(SpecimenOrObservationBase specimen, String specimenExceptionText)

			throws DerivedUnitFacadeNotSupportedException {

		TextData result;

		SpecimenDescription imageGallery = getImageGalleryWithSupportTest(

				specimen, specimenExceptionText, true);

		result = getImageTextDataWithSupportTest(imageGallery,

				specimenExceptionText);

		return result;

	}

	/**

	 * Returns the image gallery of the according specimen. Throws an exception

	 * if the attached image gallerie(s) are not supported by this facade. If no

	 * image gallery exists a new one is created if

	 * <code>createNewIfNotExists</code> is true and if specimen is not

	 * <code>null</code>.

	 * 

	 * @param specimen

	 * @param specimenText

	 * @param createNewIfNotExists

	 * @return

	 * @throws DerivedUnitFacadeNotSupportedException

	 */

	private SpecimenDescription getImageGalleryWithSupportTest(

			SpecimenOrObservationBase<?> specimen, String specimenText,

			boolean createNewIfNotExists)

			throws DerivedUnitFacadeNotSupportedException {

		if (specimen == null) {

			return null;

		}

		SpecimenDescription imageGallery;

		if (hasMultipleImageGalleries(specimen)) {

			throw new DerivedUnitFacadeNotSupportedException(specimenText

					+ " must not have more than 1 image gallery");

		} else {

			imageGallery = getImageGallery(specimen, createNewIfNotExists);

			getImageTextDataWithSupportTest(imageGallery, specimenText);

		}

		return imageGallery;

	}

	/**

	 * Returns the media holding text data element of the image gallery. Throws

	 * an exception if multiple such text data already exist. Creates a new text

	 * data if none exists and adds it to the image gallery. If image gallery is

	 * <code>null</code> nothing happens.

	 * 

	 * @param imageGallery

	 * @param textData

	 * @return

	 * @throws DerivedUnitFacadeNotSupportedException

	 */

	private TextData getImageTextDataWithSupportTest(

			SpecimenDescription imageGallery, String specimenText)

			throws DerivedUnitFacadeNotSupportedException {

		if (imageGallery == null) {

			return null;

		}

		TextData textData = null;

		for (DescriptionElementBase element : imageGallery.getElements()) {

			if (element.isInstanceOf(TextData.class)

					&& element.getFeature().equals(Feature.IMAGE())) {

				if (textData != null) {

					throw new DerivedUnitFacadeNotSupportedException(

							specimenText

									+ " must not have more than 1 image text data element in image gallery");

				}

				textData = CdmBase.deproxy(element, TextData.class);

			}

		}

		if (textData == null) {

			textData = TextData.NewInstance(Feature.IMAGE());

			imageGallery.addElement(textData);

		}

		return textData;

	}

	/**

	 * Checks, if a specimen belongs to more than one description that is an

	 * image gallery

	 * 

	 * @param derivedUnit

	 * @return

	 */

	private boolean hasMultipleImageGalleries(

			SpecimenOrObservationBase<?> derivedUnit) {

		int count = 0;

		Set<SpecimenDescription> descriptions = derivedUnit

				.getSpecimenDescriptions();

		for (SpecimenDescription description : descriptions) {

			if (description.isImageGallery()) {

				count++;

			}

		}

		return (count > 1);

	}

	/**

	 * Returns the image gallery for a specimen. If there are multiple specimen

	 * descriptions marked as image galleries an arbitrary one is chosen. If no

	 * image gallery exists, a new one is created if

	 * <code>createNewIfNotExists</code> is <code>true</code>.<Br>

	 * If specimen is <code>null</code> a null pointer exception is thrown.

	 * 

	 * @param createNewIfNotExists

	 * @return

	 */

	private SpecimenDescription getImageGallery(SpecimenOrObservationBase<?> specimen, boolean createIfNotExists) {

		SpecimenDescription result = null;

		Set<SpecimenDescription> descriptions = specimen.getSpecimenDescriptions();

		for (SpecimenDescription description : descriptions) {

			if (description.isImageGallery()) {