JAL-1479 minor refactor and housekeeping
[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   /**
52    * Get DB Source for the SIFTs Entry
53    * 
54    * @return
55    */
56   public String getDbSource();
57
58   /**
59    * Get DB version for the SIFTs Entry
60    * 
61    * @return
62    */
63   public String getDbVersion();
64
65   /**
66    * Get Number of Entities available in the SIFTs Entry
67    * 
68    * @return
69    */
70   public int getEntityCount();
71
72   /**
73    * Get a unique Entity by its Id
74    * 
75    * @param id
76    *          ID of the entity to fetch
77    * @return Entity
78    * @throws Exception
79    */
80   public Entity getEntityById(String id) throws SiftsException;
81
82   /**
83    * Get all accession Ids available in the current SIFTs entry
84    * 
85    * @return a unique set of discovered accession strings
86    */
87   public HashSet<String> getAllMappingAccession();
88
89   /**
90    * Check if the accessionId is available in current SIFTs Entry
91    * 
92    * @param accessionId
93    * @return
94    */
95   public boolean isAccessionMatched(String accessionId);
96
97   /**
98    * 
99    * @param mop
100    *          MappingOutputPojo
101    * @return Sequence<->Structure mapping as int[][]
102    * @throws SiftsException
103    */
104   public StringBuffer getMappingOutput(MappingOutputPojo mop)
105           throws SiftsException;
106
107   /**
108    * 
109    * @param seq
110    *          sequence to generate mapping against the structure
111    * @param pdbFile
112    *          PDB file for the mapping
113    * @param chain
114    *          the chain of the entry to use for mapping
115    * @return StructureMapping
116    * @throws SiftsException
117    */
118   public StructureMapping getSiftsStructureMapping(SequenceI seq,
119           String pdbFile, String chain) throws SiftsException;
120   
121   /**
122    * Get residue by residue mapping for a given Sequence and SIFTs entity
123    * 
124    * @param entityId
125    *          Id of the target entity in the SIFTs entry
126    * @param seq
127    *          SequenceI
128    * @return generated mapping
129    * @throws Exception
130    */
131   public HashMap<Integer, int[]> getGreedyMapping(String entityId,
132           SequenceI seq,
133           java.io.PrintStream os) throws SiftsException;
134 }