/*
 *                    BioJava development code
 *
 * This code may be freely distributed and modified under the
 * terms of the GNU Lesser General Public Licence.  This should
 * be distributed with the code.  If you do not have a copy,
 * see:
 *
 *      http://www.gnu.org/copyleft/lesser.html
 *
 * Copyright for this code is held jointly by the individual
 * authors.  These should be listed in @author doc comments.
 *
 * For more information on the BioJava project and its aims,
 * or to join the biojava-l mailing list, visit the home page
 * at:
 *
 *      http://www.biojava.org/
 *
 */
package org.biojava.nbio.structure.cluster;

import org.biojava.nbio.core.exceptions.CompoundNotFoundException;
import org.biojava.nbio.core.sequence.ProteinSequence;
import org.biojava.nbio.structure.Atom;
import org.biojava.nbio.structure.Structure;
import org.biojava.nbio.structure.StructureIdentifier;
import org.biojava.nbio.structure.StructureTools;

/**
 * A Subunit consists of a set of residues from a Structure, which may
 * correspond to an entire Chain, a Domain, or any subset or combination of
 * residues from them. All the residues of a Subunit are of the same type.
 * <p>
 * The Subunit object can contain additional fields for identification and
 * annotation.
 * 
 * @author Aleix Lafita
 * @since 5.0.0
 *
 */
public class Subunit {

	// Optional fields for Subunit annotation
	private String name;
	private Structure structure;
	private StructureIdentifier identifier;

	// Required fields for Subunit definition
	private Atom[] reprAtoms;
	private ProteinSequence sequence = null;

	/**
	 * A Subunit is solely defined by the coordinates of the representative
	 * Atoms of its residues. It can be identified with a StructureIdentifier
	 * and/or a name and stores a reference to the Structure from which the
	 * Atoms were obtained.
	 * 
	 * @param repAtoms
	 *            representative Atoms. It cannot be null or empty
	 * @param name
	 *            String field that identifies the Subunit. It can be null
	 * @param identifier
	 *            StructureIdentifier. It can be null
	 * @param structure
	 *            parent Structure object. It can be null
	 */
	public Subunit(Atom[] reprAtoms, String name,
			StructureIdentifier identifier, Structure structure) {

		if (reprAtoms == null)
			throw new IllegalArgumentException(
					"Representative Atom Array of the Subunit is null");
		if (reprAtoms.length==0)
			throw new IllegalArgumentException(
					"Representative Atom Array of the Subunit has 0 length");

		this.reprAtoms = reprAtoms;
		this.name = name;
		this.identifier = identifier;
		this.structure = structure;
	}

	/**
	 * Get all the representative Atoms of the Subunit. These Atoms are used for
	 * clustering and displaying the Subunit.
	 * 
	 * @return representative Atom[]
	 */
	public Atom[] getRepresentativeAtoms() {
		return reprAtoms;
	}

	/**
	 * The size of a Subunit is the number of residues it contains.
	 * 
	 * @return the size of the Subunit
	 */
	public int size() {
		return reprAtoms.length;
	}

	/**
	 * Get the protein sequence of the Subunit as String.
	 * 
	 * @return protein sequence String
	 */
	public String getProteinSequenceString() {

		if (sequence != null)
			return sequence.toString();

		StringBuilder builder = new StringBuilder();
		for (Atom a : reprAtoms)
			// This method preferred over getChemComp.getOneLetterCode because
			// it returns always X for Unknown residues
			builder.append(StructureTools.get1LetterCode(a.getGroup()
					.getPDBName()));

		return builder.toString();
	}

	/**
	 * Get the protein sequence of the Subunit.
	 * 
	 * @return sequence ProteinSequence
	 * @throws CompoundNotFoundException
	 */
	public ProteinSequence getProteinSequence()
			throws CompoundNotFoundException {

		if (sequence == null)
			sequence = new ProteinSequence(getProteinSequenceString());

		return sequence;
	}

	/**
	 * The Name of a Subunit is a free-text field, user defined.
	 * 
	 * @return the Subunit name
	 */
	public String getName() {
		return name;
	}

	/**
	 * The Name of a Subunit is a free-text field, user defined.
	 * 
	 * @param name
	 *            of the Subunit
	 */
	public void setName(String name) {
		this.name = name;
	}

	/**
	 * The parent Structure from which the Subunit atoms were obtained.
	 * 
	 * @return Structure object
	 */
	public Structure getStructure() {
		return structure;
	}

	/**
	 * The standard identifier of the Subunit.
	 * 
	 * @return StructureIdentifier object
	 */
	public StructureIdentifier getIdentifier() {
		return identifier;
	}

	@Override
	public String toString() {
		return "Subunit [Name: " + name + ", Identifier: " + identifier
				+ ", Size:" + size() + ", Sequence:" + sequence + "]";
	}

}