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;
027
028import org.biojava.nbio.structure.align.util.AtomCache;
029
030
031/**
032 * An identifier that <em>uniquely</em> identifies a whole {@link Structure} or
033 * arbitrary substructure. Common examples would be reducing a structure to a
034 * single chain, domain, or residue range.
035 *
036 * StructureIdentifiers are represented by unique strings. The getId() and fromId()
037 * methods convert to and from the string representation.
038 *
039 * Implementations should provide a constructor which takes a String. A static
040 * <tt>fromId(String)</tt> method is also recommended.
041 *
042 * @author dmyersturnbull
043 * @author Spencer Bliven
044 */
045public interface StructureIdentifier {
046
047        /**
048         * Get the String form of this identifier.
049         *
050         * It is recommended that the {@link #toString()} method also return the
051         * identifier, for consistency during serialization.
052         * @return The String form of this identifier
053         */
054        String getIdentifier();
055
056
057        /**
058         * Loads a structure encompassing the structure identified.
059         * The Structure returned should be suitable for passing as
060         * the input to {@link #reduce(Structure)}.
061         *
062         * It is recommended that the most complete structure available be returned
063         * (e.g. the full PDB) to allow processing of unselected portions where
064         * appropriate.
065         * @param AtomCache A potential sources of structures
066         * @return A Structure containing at least the atoms identified by this,
067         *  or null if Structures are not applicable.
068         * @throws StructureException For errors loading and parsing the structure
069         * @throws IOException Errors reading the structure from disk
070         */
071        Structure loadStructure(AtomCache cache) throws StructureException, IOException;
072
073        /**
074         * Convert to a canonical SubstructureIdentifier.
075         *
076         * <p>This allows all domains to be converted to a standard format String.
077         * @return A SubstructureIdentifier equivalent to this
078         * @throws StructureException Wraps exceptions that may be thrown by individual
079         *  implementations. For example, a SCOP identifier may require that the
080         *  domain definitions be available for download.
081         */
082        SubstructureIdentifier toCanonical() throws StructureException;
083
084        /**
085         * Takes a complete structure as input and reduces it to the substructure
086         * represented by this StructureIdentifier.
087         *
088         * <p>The returned structure may be a shallow copy of the input, with shared
089         * Chains, Residues, etc.
090         * @param input A full structure, e.g. as loaded from the PDB. The structure
091         * ID should match that returned by getPdbId(), if applicable.
092         * @return
093         * @throws StructureException
094         * @see StructureTools#getReducedStructure(Structure, String)
095         */
096        Structure reduce(Structure input) throws StructureException;
097
098}