Don't use Strings to hold primary key values.
[online-glom:gwt-glom.git] / src / main / java / org / glom / web / client / OnlineGlomService.java
1 /*
2  * Copyright (C) 2010, 2011 Openismus GmbH
3  *
4  * This file is part of GWT-Glom.
5  *
6  * GWT-Glom is free software: you can redistribute it and/or modify it
7  * under the terms of the GNU Lesser General Public License as published by the
8  * Free Software Foundation, either version 3 of the License, or (at your
9  * option) any later version.
10  *
11  * GWT-Glom is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
14  * for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public License
17  * along with GWT-Glom.  If not, see <http://www.gnu.org/licenses/>.
18  */
19
20 package org.glom.web.client;
21
22 import java.util.ArrayList;
23
24 import org.glom.web.shared.DataItem;
25 import org.glom.web.shared.DetailsLayoutAndData;
26 import org.glom.web.shared.DocumentInfo;
27 import org.glom.web.shared.Documents;
28 import org.glom.web.shared.NavigationRecord;
29 import org.glom.web.shared.PrimaryKeyItem;
30 import org.glom.web.shared.layout.LayoutGroup;
31
32 import com.google.gwt.user.client.rpc.RemoteService;
33 import com.google.gwt.user.client.rpc.RemoteServiceRelativePath;
34
35 @RemoteServiceRelativePath("libGlom")
36 public interface OnlineGlomService extends RemoteService {
37
38         DocumentInfo getDocumentInfo(String documentID);
39
40         /**
41          * Gets a {@link LayoutGroup} for the given Glom document and table name.
42          * 
43          * @param documentID
44          *            identifier for the Glom document
45          * @param tableName
46          *            name of the table in the Glom document or an empty {@link String} ("") to get the layout for the
47          *            default table
48          * @return filled in {@link LayoutGroup}
49          */
50         LayoutGroup getListViewLayout(String documentID, String tableName);
51
52         /**
53          * Retrieves data for a list view table.
54          * 
55          * @param documentID
56          *            identifier for the Glom document
57          * @param tableName
58          *            name of the table in the Glom document or an empty {@link String} ("") to get the layout for the
59          *            default table
60          * @param start
61          *            the start index in the data result set from the SQL query that should be retrieved
62          * @param length
63          *            the number of rows of data to retrieve
64          * @return an {@link ArrayList} of {@link DataItem} arrays that represents the requested data
65          */
66         ArrayList<DataItem[]> getListViewData(String documentID, String tableName, int start, int length);
67
68         /**
69          * Retrieves sorted data for a list view table.
70          * 
71          * @param documentID
72          *            identifier for the Glom document
73          * @param tableName
74          *            name of the table in the Glom document or an empty {@link String} ("") to get the layout for the
75          *            default table
76          * @param start
77          *            the start index in the data result set from the SQL query that should be retrieved
78          * @param length
79          *            the number of rows of data to retrieve
80          * @param sortColumnIndex
81          *            the index of the column to sort
82          * @param ascending
83          *            <code>true</code> if the column should be sorted in ascending order, <code>false</code> if the column
84          *            should be sorted in descending order
85          * @return an {@link ArrayList} of {@link DataItem} arrays that represents the requested data
86          */
87         ArrayList<DataItem[]> getSortedListViewData(String documentID, String tableName, int start, int length,
88                         int sortColumnIndex, boolean isAscending);
89
90         /**
91          * Gets a list of Glom documents found in the configured directory.
92          * 
93          * @return an {@link ArrayList<String>} of Glom document titles. If the list is empty, no glom documents were found
94          *         in the configured directory because it's empty or the directory is not configured correctly.
95          */
96         Documents getDocuments();
97
98         /**
99          * Checks if the PostgreSQL authentication has been set for this document.
100          * 
101          * @param documentID
102          *            identifier for the Glom document
103          * @return true if the authentication has been set, false if it hasn't
104          */
105         boolean isAuthenticated(String documentID);
106
107         /**
108          * Checks if the provided PostgreSQL username and password are correct for the specified glom document. If the
109          * information is correct it is saved for future access.
110          * 
111          * @param documentID
112          *            identifier for the Glom document
113          * @param username
114          *            the PostgreSQL username
115          * @param password
116          *            the POstgreSQL password
117          * @return true if username and password are correct, false otherwise
118          */
119         boolean checkAuthentication(String documentID, String username, String password);
120
121         /**
122          * Gets data for the details view.
123          * 
124          * Note: This method is not currently being used. It will be useful when navigation through the details view is
125          * added by creating a data provider for the details view.
126          * 
127          * TODO: Remove above comment when this method is being used.
128          * 
129          * @param documentID
130          *            identifier for the Glom document
131          * @param tableName
132          *            name of the table in the Glom document or an empty {@link String} ("") to get the layout for the
133          *            default table
134          * @param primaryKeyValue
135          *            value of the primary key in the specified Glom table to use in the query
136          * @return the result of the SQL query as an array of {@link DataItem}s
137          */
138         DataItem[] getDetailsData(String documentID, String tableName, PrimaryKeyItem primaryKeyValue);
139
140         /**
141          * Gets a {@link DetailsLayoutAndData} object that contains the layout and data of the details view.
142          * 
143          * @param documentID
144          *            identifier for the Glom document
145          * @param tableName
146          *            name of the table in the Glom document or an empty {@link String} ("") to get the layout for the
147          *            default table
148          * @param primaryKeyValue
149          *            value of the primary key in the specified Glom table to use in the query
150          * @return a {@link DetailsLayoutAndData} object for the layout and initial data of the details view.
151          */
152         DetailsLayoutAndData getDetailsLayoutAndData(String documentID, String tableName, PrimaryKeyItem primaryKeyValue);
153
154         /**
155          * Retrieves data for the related list table with the specified relationship name and foreign key value.
156          * 
157          * @param documentID
158          *            identifier for the Glom document
159          * @param tableName
160          *            name of the table in the Glom document or an empty {@link String} ("") to get the layout for the
161          *            default table
162          * @param relationshipName
163          *            name of the relationship to use for setting up the SQL query
164          * @param start
165          *            the start index in the data result set from the SQL query that should be retrieved
166          * @param length
167          *            the number of rows of data to retrieve
168          * @param foreignKeyValue
169          *            the value of the foreign key
170          * @return an {@link ArrayList} of {@link DataItem} arrays that represents the requested data
171          */
172         ArrayList<DataItem[]> getRelatedListData(String documentID, String tableName, String relationshipName,
173                         PrimaryKeyItem foreignKeyValue, int start, int length);
174
175         /**
176          * Retrieves sorted data for the related list table with the specified relationship name and foreign key value.
177          * 
178          * @param documentID
179          *            identifier for the Glom document
180          * @param tableName
181          *            name of the table in the Glom document or an empty {@link String} ("") to get the layout for the
182          *            default table
183          * @param relationshipName
184          *            name of the relationship to use for setting up the SQL query
185          * @param foreignKeyValue
186          *            the value of the foreign key
187          * @param start
188          *            the start index in the data result set from the SQL query that should be retrieved
189          * @param length
190          *            the number of rows of data to retrieve
191          * @param sortColumnIndex
192          *            the index of the column to sort
193          * @param ascending
194          *            <code>true</code> if the column should be sorted in ascending order, <code>false</code> if the column
195          *            should be sorted in descending order
196          * @return an {@link ArrayList} of {@link DataItem} arrays that represents the requested data
197          */
198         ArrayList<DataItem[]> getSortedRelatedListData(String documentID, String tableName, String relationshipName,
199                         PrimaryKeyItem foreignKeyValue, int start, int length, int sortColumnIndex, boolean ascending);
200
201         /**
202          * Gets the expected row count for the related list table with the specified relationship name and foreign key
203          * value.
204          * 
205          * @param documentID
206          *            identifier for the Glom document
207          * @param tableName
208          *            name of the table in the Glom document or an empty {@link String} ("") to get the layout for the
209          *            default table
210          * @param relationshipName
211          *            name of the relationship to use for setting up the SQL query
212          * @param foreignKeyValue
213          *            the value of the foreign key
214          * @return the expected row count
215          */
216         int getRelatedListRowCount(String documentID, String tableName, String relationshipName,
217                         PrimaryKeyItem foreignKeyValue);
218
219         NavigationRecord getSuitableRecordToViewDetails(String documentID, String tableName, String relationshipName,
220                         PrimaryKeyItem primaryKeyValue);
221
222 }