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}