JAL-2788 possible adjustments to sequence accesses
[jalview.git] / src / jalview / api / SiftsClientI.java
1 /*
2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
4  * 
5  * This file is part of Jalview.
6  * 
7  * Jalview is free software: you can redistribute it and/or
8  * modify it under the terms of the GNU General Public License 
9  * as published by the Free Software Foundation, either version 3
10  * of the License, or (at your option) any later version.
11  *  
12  * Jalview is distributed in the hope that it will be useful, but 
13  * WITHOUT ANY WARRANTY; without even the implied warranty 
14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
15  * PURPOSE.  See the GNU General Public License for more details.
16  * 
17  * You should have received a copy of the GNU General Public License
18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
19  * The Jalview Authors are detailed in the 'AUTHORS' file.
20  */
21 package jalview.api;
22
23 import jalview.datamodel.SequenceI;
24 import jalview.structure.StructureMapping;
25 import jalview.ws.sifts.MappingOutputPojo;
26 import jalview.ws.sifts.SiftsException;
27 import jalview.xml.binding.sifts.Entry.Entity;
28
29 import java.util.HashMap;
30 import java.util.HashSet;
31
32 // JBPComment: this isn't a top-level Jalview API - should be in its own package api
33
34 public interface SiftsClientI
35 {
36   /**
37    * Get the DB Accession Id for the SIFTs Entry
38    * 
39    * @return
40    */
41   public String getDbAccessionId();
42
43   /**
44    * Get DB Coordinate system for the SIFTs Entry
45    * 
46    * @return
47    */
48   public String getDbCoordSys();
49
50   /**
51    * Get DB Source for the SIFTs Entry
52    * 
53    * @return
54    */
55   public String getDbSource();
56
57   /**
58    * Get DB version for the SIFTs Entry
59    * 
60    * @return
61    */
62   public String getDbVersion();
63
64   /**
65    * Get Number of Entities available in the SIFTs Entry
66    * 
67    * @return
68    */
69   public int getEntityCount();
70
71   /**
72    * Get a unique Entity by its Id
73    * 
74    * @param id
75    *          ID of the entity to fetch
76    * @return Entity
77    * @throws Exception
78    */
79   public Entity getEntityById(String id) throws SiftsException;
80
81   /**
82    * Get all accession Ids available in the current SIFTs entry
83    * 
84    * @return a unique set of discovered accession strings
85    */
86   public HashSet<String> getAllMappingAccession();
87
88   /**
89    * Check if the accessionId is available in current SIFTs Entry
90    * 
91    * @param accessionId
92    * @return
93    */
94   public boolean isAccessionMatched(String accessionId);
95
96   /**
97    * 
98    * @param mop
99    *          MappingOutputPojo
100    * @return Sequence<->Structure mapping as int[][]
101    * @throws SiftsException
102    */
103   public StringBuilder getMappingOutput(MappingOutputPojo mop)
104           throws SiftsException;
105
106   /**
107    * 
108    * @param seq
109    *          sequence to generate mapping against the structure
110    * @param pdbFile
111    *          PDB file for the mapping
112    * @param chain
113    *          the chain of the entry to use for mapping
114    * @return StructureMapping
115    * @throws SiftsException
116    */
117   public StructureMapping getSiftsStructureMapping(SequenceI seq,
118           String pdbFile, String chain) throws SiftsException;
119
120   /**
121    * Get residue by residue mapping for a given Sequence and SIFTs entity
122    * 
123    * @param entityId
124    *          Id of the target entity in the SIFTs entry
125    * @param seq
126    *          SequenceI
127    * @return generated mapping
128    * @throws Exception
129    */
130   public HashMap<Integer, int[]> getGreedyMapping(String entityId,
131           SequenceI seq, java.io.PrintStream os) throws SiftsException;
132 }