001/*
002 *                    BioJava development code
003 *
004 * This code may be freely distributed and modified under the
005 * terms of the GNU Lesser General Public Licence.  This should
006 * be distributed with the code.  If you do not have a copy,
007 * see:
008 *
009 *      http://www.gnu.org/copyleft/lesser.html
010 *
011 * Copyright for this code is held jointly by the individual
012 * authors.  These should be listed in @author doc comments.
013 *
014 * For more information on the BioJava project and its aims,
015 * or to join the biojava-l mailing list, visit the home page
016 * at:
017 *
018 *      http://www.biojava.org/
019 *
020 * Created on December 19, 2013
021 * Author: Douglas Myers-Turnbull
022 */
023
024package org.biojava.nbio.structure;
025
026import java.io.IOException;
027import java.io.Serializable;
028
029import org.biojava.nbio.structure.align.util.AtomCache;
030
031
032/**
033 * An identifier that <em>uniquely</em> identifies a whole {@link Structure} or
034 * arbitrary substructure. Common examples would be reducing a structure to a
035 * single chain, domain, or residue range.
036 *
037 * StructureIdentifiers are represented by unique strings. The getId() and fromId()
038 * methods convert to and from the string representation.
039 *
040 * Implementations should provide a constructor which takes a String. A static
041 * <tt>fromId(String)</tt> method is also recommended.
042 *
043 * @author dmyersturnbull
044 * @author Spencer Bliven
045 */
046public interface StructureIdentifier extends Serializable {
047
048        /**
049         * Get the String form of this identifier.
050         *
051         * It is recommended that the {@link #toString()} method also return the
052         * identifier, for consistency during serialization.
053         * @return The String form of this identifier
054         */
055        String getIdentifier();
056
057
058        /**
059         * Loads a structure encompassing the structure identified.
060         * The Structure returned should be suitable for passing as
061         * the input to {@link #reduce(Structure)}.
062         *
063         * It is recommended that the most complete structure available be returned
064         * (e.g. the full PDB) to allow processing of unselected portions where
065         * appropriate.
066         * @param AtomCache A potential sources of structures
067         * @return A Structure containing at least the atoms identified by this,
068         *  or null if Structures are not applicable.
069         * @throws StructureException For errors loading and parsing the structure
070         * @throws IOException Errors reading the structure from disk
071         */
072        Structure loadStructure(AtomCache cache) throws StructureException, IOException;
073
074        /**
075         * Convert to a canonical SubstructureIdentifier.
076         *
077         * <p>This allows all domains to be converted to a standard format String.
078         * @return A SubstructureIdentifier equivalent to this
079         * @throws StructureException Wraps exceptions that may be thrown by individual
080         *  implementations. For example, a SCOP identifier may require that the
081         *  domain definitions be available for download.
082         */
083        SubstructureIdentifier toCanonical() throws StructureException;
084
085        /**
086         * Takes a complete structure as input and reduces it to the substructure
087         * represented by this StructureIdentifier.
088         *
089         * <p>The returned structure may be a shallow copy of the input, with shared
090         * Chains, Residues, etc.
091         * @param input A full structure, e.g. as loaded from the PDB. The structure
092         * ID should match that returned by getPdbId(), if applicable.
093         * @return
094         * @throws StructureException
095         * @see StructureTools#getReducedStructure(Structure, String)
096         */
097        Structure reduce(Structure input) throws StructureException;
098
099}