Add a Field class and implement some loading of it in Document.
[online-glom:gwt-glom.git] / src / main / java / org / glom / web / server / ConfiguredDocument.java
1 /*
2  * Copyright (C) 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.server;
21
22 import java.beans.PropertyVetoException;
23 import java.sql.Connection;
24 import java.sql.SQLException;
25 import java.util.ArrayList;
26 import java.util.Collection;
27 import java.util.List;
28 import java.util.Locale;
29
30 import org.apache.commons.lang3.StringUtils;
31 import org.glom.libglom.Field.glom_field_type;
32 import org.glom.libglom.LayoutGroupVector;
33 import org.glom.libglom.LayoutItemVector;
34 import org.glom.libglom.LayoutItem_CalendarPortal;
35 import org.glom.libglom.LayoutItem_Field;
36 import org.glom.libglom.LayoutItem_Notebook;
37 import org.glom.libglom.LayoutItem_Portal;
38 import org.glom.libglom.NumericFormat;
39 import org.glom.libglom.Relationship;
40 import org.glom.libglom.StringVector;
41 import org.glom.web.server.database.DetailsDBAccess;
42 import org.glom.web.server.database.ListViewDBAccess;
43 import org.glom.web.server.database.RelatedListDBAccess;
44 import org.glom.web.server.database.RelatedListNavigation;
45 import org.glom.web.shared.DataItem;
46 import org.glom.web.shared.DocumentInfo;
47 import org.glom.web.shared.GlomNumericFormat;
48 import org.glom.web.shared.NavigationRecord;
49 import org.glom.web.shared.Reports;
50 import org.glom.web.shared.TypedDataItem;
51 import org.glom.web.shared.layout.Formatting;
52 import org.glom.web.shared.layout.LayoutGroup;
53 import org.glom.web.shared.layout.LayoutItem;
54 import org.glom.web.shared.layout.LayoutItemField;
55 import org.glom.web.shared.layout.LayoutItemNotebook;
56 import org.glom.web.shared.layout.LayoutItemPortal;
57 import org.glom.web.shared.libglom.Document;
58 import org.glom.web.shared.libglom.Field;
59 import org.glom.web.shared.libglom.Report;
60
61 import com.mchange.v2.c3p0.ComboPooledDataSource;
62
63 /**
64  * A class to hold configuration information for a given Glom document. This class retrieves layout information from
65  * libglom and data from the underlying PostgreSQL database.
66  */
67 final class ConfiguredDocument {
68
69         private Document document;
70         private ComboPooledDataSource cpds;
71         private boolean authenticated = false;
72         private String documentID = "";
73         private String defaultLocaleID = "";
74
75         @SuppressWarnings("unused")
76         private ConfiguredDocument() {
77                 // disable default constructor
78         }
79
80         ConfiguredDocument(final Document document) throws PropertyVetoException {
81
82                 // load the jdbc driver
83                 cpds = new ComboPooledDataSource();
84
85                 // We don't support sqlite or self-hosting yet.
86                 if (document.get_hosting_mode() != Document.HostingMode.HOSTING_MODE_POSTGRES_CENTRAL) {
87                         Log.fatal("Error configuring the database connection." + " Only central PostgreSQL hosting is supported.");
88                         // FIXME: Throw exception?
89                 }
90
91                 try {
92                         cpds.setDriverClass("org.postgresql.Driver");
93                 } catch (final PropertyVetoException e) {
94                         Log.fatal("Error loading the PostgreSQL JDBC driver."
95                                         + " Is the PostgreSQL JDBC jar available to the servlet?", e);
96                         throw e;
97                 }
98
99                 // setup the JDBC driver for the current glom document
100                 cpds.setJdbcUrl("jdbc:postgresql://" + document.get_connection_server() + ":" + document.get_connection_port()
101                                 + "/" + document.get_connection_database());
102
103                 this.document = document;
104         }
105
106         /**
107          * Sets the username and password for the database associated with the Glom document.
108          * 
109          * @return true if the username and password works, false otherwise
110          */
111         boolean setUsernameAndPassword(final String username, final String password) throws SQLException {
112                 cpds.setUser(username);
113                 cpds.setPassword(password);
114
115                 final int acquireRetryAttempts = cpds.getAcquireRetryAttempts();
116                 cpds.setAcquireRetryAttempts(1);
117                 Connection conn = null;
118                 try {
119                         // FIXME find a better way to check authentication
120                         // it's possible that the connection could be failing for another reason
121                         conn = cpds.getConnection();
122                         authenticated = true;
123                 } catch (final SQLException e) {
124                         Log.info(Utils.getFileName(document.get_file_uri()), e.getMessage());
125                         Log.info(Utils.getFileName(document.get_file_uri()),
126                                         "Connection Failed. Maybe the username or password is not correct.");
127                         authenticated = false;
128                 } finally {
129                         if (conn != null)
130                                 conn.close();
131                         cpds.setAcquireRetryAttempts(acquireRetryAttempts);
132                 }
133                 return authenticated;
134         }
135
136         Document getDocument() {
137                 return document;
138         }
139
140         ComboPooledDataSource getCpds() {
141                 return cpds;
142         }
143
144         boolean isAuthenticated() {
145                 return authenticated;
146         }
147
148         String getDocumentID() {
149                 return documentID;
150         }
151
152         void setDocumentID(final String documentID) {
153                 this.documentID = documentID;
154         }
155
156         String getDefaultLocaleID() {
157                 return defaultLocaleID;
158         }
159
160         void setDefaultLocaleID(final String localeID) {
161                 this.defaultLocaleID = localeID;
162         }
163
164         /**
165          * @return
166          */
167         DocumentInfo getDocumentInfo(final String localeID) {
168                 final DocumentInfo documentInfo = new DocumentInfo();
169
170                 // get arrays of table names and titles, and find the default table index
171                 final StringVector tablesVec = document.get_table_names();
172
173                 final int numTables = Utils.safeLongToInt(tablesVec.size());
174                 // we don't know how many tables will be hidden so we'll use half of the number of tables for the default size
175                 // of the ArrayList
176                 final ArrayList<String> tableNames = new ArrayList<String>(numTables / 2);
177                 final ArrayList<String> tableTitles = new ArrayList<String>(numTables / 2);
178                 boolean foundDefaultTable = false;
179                 int visibleIndex = 0;
180                 for (int i = 0; i < numTables; i++) {
181                         final String tableName = tablesVec.get(i);
182                         if (!document.get_table_is_hidden(tableName)) {
183                                 tableNames.add(tableName);
184                                 // JNI is "expensive", the comparison will only be called if we haven't already found the default table
185                                 if (!foundDefaultTable && tableName.equals(document.get_default_table())) {
186                                         documentInfo.setDefaultTableIndex(visibleIndex);
187                                         foundDefaultTable = true;
188                                 }
189                                 tableTitles.add(document.get_table_title(tableName, localeID));
190                                 visibleIndex++;
191                         }
192                 }
193
194                 // set everything we need
195                 documentInfo.setTableNames(tableNames);
196                 documentInfo.setTableTitles(tableTitles);
197                 documentInfo.setTitle(document.get_database_title(localeID));
198
199                 // Fetch arrays of locale IDs and titles:
200                 final StringVector localesVec = document.get_translation_available_locales();
201                 final int numLocales = Utils.safeLongToInt(localesVec.size());
202                 final ArrayList<String> localeIDs = new ArrayList<String>(numLocales);
203                 final ArrayList<String> localeTitles = new ArrayList<String>(numLocales);
204                 for (int i = 0; i < numLocales; i++) {
205                         final String this_localeID = localesVec.get(i);
206                         localeIDs.add(this_localeID);
207
208                         // Use java.util.Locale to get a title for the locale:
209                         final String[] locale_parts = this_localeID.split("_");
210                         String locale_lang = this_localeID;
211                         if (locale_parts.length > 0)
212                                 locale_lang = locale_parts[0];
213                         String locale_country = "";
214                         if (locale_parts.length > 1)
215                                 locale_country = locale_parts[1];
216
217                         final Locale locale = new Locale(locale_lang, locale_country);
218                         final String title = locale.getDisplayName(locale);
219                         localeTitles.add(title);
220                 }
221                 documentInfo.setLocaleIDs(localeIDs);
222                 documentInfo.setLocaleTitles(localeTitles);
223
224                 return documentInfo;
225         }
226
227         /*
228          * Gets the layout group for the list view using the defined layout list in the document or the table fields if
229          * there's no defined layout group for the list view.
230          */
231         private org.glom.libglom.LayoutGroup getValidListViewLayoutGroup(final String tableName) {
232
233                 final LayoutGroupVector layoutGroupVec = document.get_data_layout_groups("list", tableName);
234
235                 final int listViewLayoutGroupSize = Utils.safeLongToInt(layoutGroupVec.size());
236                 org.glom.libglom.LayoutGroup libglomLayoutGroup = null;
237                 if (listViewLayoutGroupSize > 0) {
238                         // a list layout group is defined; we can use the first group as the list
239                         if (listViewLayoutGroupSize > 1)
240                                 Log.warn(documentID, tableName, "The size of the list layout group is greater than 1. "
241                                                 + "Attempting to use the first item for the layout list view.");
242
243                         libglomLayoutGroup = layoutGroupVec.get(0);
244                 } else {
245                         // a list layout group is *not* defined; we are going make a libglom layout group from the list of fields
246                         Log.info(documentID, tableName,
247                                         "A list layout is not defined for this table. Displaying a list layout based on the field list.");
248
249                         final List<Field> fieldsVec = document.get_table_fields(tableName);
250                         libglomLayoutGroup = new org.glom.libglom.LayoutGroup();
251                         for (int i = 0; i < fieldsVec.size(); i++) {
252                                 final Field field = fieldsVec.get(i);
253                                 final LayoutItem_Field layoutItemField = new LayoutItem_Field();
254                                 layoutItemField.set_full_field_details(field);
255                                 libglomLayoutGroup.add_item(layoutItemField);
256                         }
257                 }
258
259                 return libglomLayoutGroup;
260         }
261
262         ArrayList<DataItem[]> getListViewData(String tableName, final String quickFind, final int start, final int length,
263                         final boolean useSortClause, final int sortColumnIndex, final boolean isAscending) {
264                 // Validate the table name.
265                 tableName = getTableNameToUse(tableName);
266
267                 // Get the libglom LayoutGroup that represents the list view.
268                 final org.glom.libglom.LayoutGroup libglomLayoutGroup = getValidListViewLayoutGroup(tableName);
269
270                 // Create a database access object for the list view.
271                 final ListViewDBAccess listViewDBAccess = new ListViewDBAccess(document, documentID, cpds, tableName,
272                                 libglomLayoutGroup);
273
274                 // Return the data.
275                 return listViewDBAccess.getData(quickFind, start, length, useSortClause, sortColumnIndex, isAscending);
276         }
277
278         DataItem[] getDetailsData(String tableName, final TypedDataItem primaryKeyValue) {
279                 // Validate the table name.
280                 tableName = getTableNameToUse(tableName);
281
282                 final DetailsDBAccess detailsDBAccess = new DetailsDBAccess(document, documentID, cpds, tableName);
283
284                 return detailsDBAccess.getData(primaryKeyValue);
285         }
286
287         ArrayList<DataItem[]> getRelatedListData(String tableName, final String relationshipName,
288                         final TypedDataItem foreignKeyValue, final int start, final int length, final boolean useSortClause,
289                         final int sortColumnIndex, final boolean isAscending) {
290                 // Validate the table name.
291                 tableName = getTableNameToUse(tableName);
292
293                 // Create a database access object for the related list
294                 final RelatedListDBAccess relatedListDBAccess = new RelatedListDBAccess(document, documentID, cpds, tableName,
295                                 relationshipName);
296
297                 // Return the data
298                 return relatedListDBAccess.getData(start, length, foreignKeyValue, useSortClause, sortColumnIndex, isAscending);
299         }
300
301         ArrayList<LayoutGroup> getDetailsLayoutGroup(String tableName, final String localeID) {
302                 // Validate the table name.
303                 tableName = getTableNameToUse(tableName);
304
305                 // Get the details layout group information for each LayoutGroup in the LayoutGroupVector
306                 final LayoutGroupVector layoutGroupVec = document.get_data_layout_groups("details", tableName);
307                 final ArrayList<LayoutGroup> layoutGroups = new ArrayList<LayoutGroup>();
308                 for (int i = 0; i < layoutGroupVec.size(); i++) {
309                         final org.glom.libglom.LayoutGroup libglomLayoutGroup = layoutGroupVec.get(i);
310
311                         // satisfy the precondition of getDetailsLayoutGroup(String, org.glom.libglom.LayoutGroup)
312                         if (libglomLayoutGroup == null)
313                                 continue;
314
315                         layoutGroups.add(getDetailsLayoutGroup(tableName, libglomLayoutGroup, localeID));
316                 }
317
318                 return layoutGroups;
319         }
320
321         /*
322          * Gets the expected row count for a related list.
323          */
324         int getRelatedListRowCount(String tableName, final String relationshipName, final TypedDataItem foreignKeyValue) {
325                 // Validate the table name.
326                 tableName = getTableNameToUse(tableName);
327
328                 // Create a database access object for the related list
329                 final RelatedListDBAccess relatedListDBAccess = new RelatedListDBAccess(document, documentID, cpds, tableName,
330                                 relationshipName);
331
332                 // Return the row count
333                 return relatedListDBAccess.getExpectedResultSize(foreignKeyValue);
334         }
335
336         NavigationRecord getSuitableRecordToViewDetails(String tableName, final String relationshipName,
337                         final TypedDataItem primaryKeyValue) {
338                 // Validate the table name.
339                 tableName = getTableNameToUse(tableName);
340
341                 final RelatedListNavigation relatedListNavigation = new RelatedListNavigation(document, documentID, cpds,
342                                 tableName, relationshipName);
343
344                 return relatedListNavigation.getNavigationRecord(primaryKeyValue);
345         }
346
347         LayoutGroup getListViewLayoutGroup(String tableName, final String localeID) {
348                 // Validate the table name.
349                 tableName = getTableNameToUse(tableName);
350
351                 final org.glom.libglom.LayoutGroup libglomLayoutGroup = getValidListViewLayoutGroup(tableName);
352
353                 return getLayoutGroupFromLiblomLayoutGroup(tableName, libglomLayoutGroup, localeID);
354         }
355
356         /**
357          * @param tableName
358          * @param libglomLayoutGroup
359          * @param localeID
360          * @return
361          */
362         private LayoutGroup getLayoutGroupFromLiblomLayoutGroup(final String tableName,
363                         final org.glom.libglom.LayoutGroup libglomLayoutGroup, final String localeID) {
364                 final LayoutGroup layoutGroup = new LayoutGroup(); // the object that will be returned
365                 int primaryKeyIndex = -1;
366
367                 // look at each child item
368                 final LayoutItemVector layoutItemsVec = libglomLayoutGroup.get_items();
369                 final int numItems = Utils.safeLongToInt(layoutItemsVec.size());
370                 for (int i = 0; i < numItems; i++) {
371                         final org.glom.libglom.LayoutItem libglomLayoutItem = layoutItemsVec.get(i);
372
373                         // TODO add support for other LayoutItems (Text, Image, Button etc.)
374                         final LayoutItem_Field libglomLayoutItemField = LayoutItem_Field.cast_dynamic(libglomLayoutItem);
375                         if (libglomLayoutItemField != null) {
376                                 layoutGroup.addItem(convertToGWTGlomLayoutItemField(libglomLayoutItemField, localeID, false));
377                                 final Field field = libglomLayoutItemField.get_full_field_details();
378                                 if (field.get_primary_key())
379                                         primaryKeyIndex = i;
380                         } else {
381                                 // TODO: We can implement this easily when we replace libglom, because then we won't need to translate
382                                 // libglom items to our own item classes here.
383                                 Log.info(documentID, tableName,
384                                                 "Ignoring unknown list LayoutItem of type " + libglomLayoutItem.get_part_type_name() + ".");
385                                 continue;
386                         }
387                 }
388
389                 // set the expected result size for list view tables
390                 final ListViewDBAccess listViewDBAccess = new ListViewDBAccess(document, documentID, cpds, tableName,
391                                 libglomLayoutGroup);
392                 layoutGroup.setExpectedResultSize(listViewDBAccess.getExpectedResultSize());
393
394                 // Set the primary key index for the table
395                 if (primaryKeyIndex < 0) {
396                         // Add a LayoutItemField for the primary key to the end of the item list in the LayoutGroup because it
397                         // doesn't already contain a primary key.
398                         Field primaryKey = null;
399                         final List<Field> fieldsVec = document.get_table_fields(tableName);
400                         for (int i = 0; i < Utils.safeLongToInt(fieldsVec.size()); i++) {
401                                 final Field field = fieldsVec.get(i);
402                                 if (field.get_primary_key()) {
403                                         primaryKey = field;
404                                         break;
405                                 }
406                         }
407                         if (primaryKey != null) {
408                                 final LayoutItem_Field libglomLayoutItemField = new LayoutItem_Field();
409                                 libglomLayoutItemField.set_full_field_details(primaryKey);
410                                 layoutGroup.addItem(convertToGWTGlomLayoutItemField(libglomLayoutItemField, localeID, false));
411                                 layoutGroup.setPrimaryKeyIndex(layoutGroup.getItems().size() - 1);
412                                 layoutGroup.setHiddenPrimaryKey(true);
413                         } else {
414                                 Log.error(document.get_database_title_original(), tableName,
415                                                 "A primary key was not found in the FieldVector for this table. Navigation buttons will not work.");
416                         }
417
418                 } else {
419                         layoutGroup.setPrimaryKeyIndex(primaryKeyIndex);
420                 }
421
422                 layoutGroup.setTableName(tableName);
423
424                 return layoutGroup;
425         }
426
427         /*
428          * Gets a recursively defined Details LayoutGroup DTO for the specified libglom LayoutGroup object. This is used for
429          * getting layout information for the details view.
430          * 
431          * @param documentID Glom document identifier
432          * 
433          * @param tableName table name in the specified Glom document
434          * 
435          * @param libglomLayoutGroup libglom LayoutGroup to convert
436          * 
437          * @precondition libglomLayoutGroup must not be null
438          * 
439          * @return {@link LayoutGroup} object that represents the layout for the specified {@link
440          * org.glom.libglom.LayoutGroup}
441          */
442         private LayoutGroup getDetailsLayoutGroup(final String tableName,
443                         final org.glom.libglom.LayoutGroup libglomLayoutGroup, final String localeID) {
444                 final LayoutGroup layoutGroup = new LayoutGroup();
445                 layoutGroup.setColumnCount(Utils.safeLongToInt(libglomLayoutGroup.get_columns_count()));
446                 final String layoutGroupTitle = libglomLayoutGroup.get_title(localeID);
447                 if (StringUtils.isEmpty(layoutGroupTitle))
448                         layoutGroup.setName(libglomLayoutGroup.get_name());
449                 else
450                         layoutGroup.setTitle(layoutGroupTitle);
451
452                 // look at each child item
453                 final LayoutItemVector layoutItemsVec = libglomLayoutGroup.get_items();
454                 for (int i = 0; i < layoutItemsVec.size(); i++) {
455                         final org.glom.libglom.LayoutItem libglomLayoutItem = layoutItemsVec.get(i);
456
457                         // just a safety check
458                         if (libglomLayoutItem == null)
459                                 continue;
460
461                         org.glom.web.shared.layout.LayoutItem layoutItem = null;
462                         final org.glom.libglom.LayoutGroup group = org.glom.libglom.LayoutGroup.cast_dynamic(libglomLayoutItem);
463                         if (group != null) {
464                                 // libglomLayoutItem is a LayoutGroup
465                                 final LayoutItem_Portal libglomLayoutItemPortal = LayoutItem_Portal.cast_dynamic(group);
466                                 if (libglomLayoutItemPortal != null) {
467                                         // group is a LayoutItem_Portal
468                                         final LayoutItemPortal layoutItemPortal = createLayoutItemPortalDTO(tableName,
469                                                         libglomLayoutItemPortal, localeID);
470                                         if (layoutItemPortal == null)
471                                                 continue;
472                                         layoutItem = layoutItemPortal;
473
474                                 } else {
475                                         // libglomLayoutItem is a LayoutGroup
476                                         final LayoutItem_Notebook libglomLayoutItemNotebook = LayoutItem_Notebook.cast_dynamic(group);
477                                         if (libglomLayoutItemNotebook != null) {
478                                                 // group is a LayoutItem_Notebook
479                                                 final LayoutGroup tempLayoutGroup = getDetailsLayoutGroup(tableName, libglomLayoutItemNotebook,
480                                                                 localeID);
481                                                 final LayoutItemNotebook layoutItemNotebook = new LayoutItemNotebook();
482                                                 for (final LayoutItem item : tempLayoutGroup.getItems()) {
483                                                         layoutItemNotebook.addItem(item);
484                                                 }
485                                                 layoutItemNotebook.setName(tableName);
486                                                 layoutItem = layoutItemNotebook;
487                                         } else {
488                                                 // group is *not* a LayoutItem_Portal or a LayoutItem_Notebook
489                                                 // recurse into child groups
490                                                 layoutItem = getDetailsLayoutGroup(tableName, group, localeID);
491                                         }
492                                 }
493                         } else {
494                                 // libglomLayoutItem is *not* a LayoutGroup
495                                 // create LayoutItem DTOs based on the the libglom type
496                                 // TODO add support for other LayoutItems (Text, Image, Button etc.)
497                                 final LayoutItem_Field libglomLayoutItemField = LayoutItem_Field.cast_dynamic(libglomLayoutItem);
498                                 if (libglomLayoutItemField != null) {
499
500                                         final LayoutItemField layoutItemField = convertToGWTGlomLayoutItemField(libglomLayoutItemField,
501                                                         localeID, true);
502
503                                         // Set the full field details with updated field details from the document.
504                                         libglomLayoutItemField.set_full_field_details(document.get_field(
505                                                         libglomLayoutItemField.get_table_used(tableName), libglomLayoutItemField.get_name()));
506
507                                         // Determine if the field should have a navigation button and set this in the DTO.
508                                         final Relationship fieldUsedInRelationshipToOne = new Relationship();
509                                         final boolean addNavigation = false; //TODO: Glom.layout_field_should_have_navigation(tableName,
510                                                         // libglomLayoutItemField, document, fieldUsedInRelationshipToOne);
511                                         layoutItemField.setAddNavigation(addNavigation);
512
513                                         // Set the the name of the table to navigate to if navigation should be enabled.
514                                         if (addNavigation) {
515                                                 // It's not possible to directly check if fieldUsedInRelationshipToOne is
516                                                 // null because of the way that the glom_sharedptr macro works. This workaround accomplishes the
517                                                 // same task.
518                                                 String tableNameUsed;
519                                                 try {
520                                                         final Relationship temp = new Relationship();
521                                                         temp.equals(fieldUsedInRelationshipToOne); // this will throw an NPE if
522                                                         // fieldUsedInRelationshipToOne is null
523                                                         // fieldUsedInRelationshipToOne is *not* null
524                                                         tableNameUsed = fieldUsedInRelationshipToOne.get_to_table();
525
526                                                 } catch (final NullPointerException e) {
527                                                         // fieldUsedInRelationshipToOne is null
528                                                         tableNameUsed = libglomLayoutItemField.get_table_used(tableName);
529                                                 }
530
531                                                 // Set the navigation table name only if it's not different than the current table name.
532                                                 if (!tableName.equals(tableNameUsed)) {
533                                                         layoutItemField.setNavigationTableName(tableNameUsed);
534                                                 }
535                                         }
536
537                                         layoutItem = layoutItemField;
538
539                                 } else {
540                                         Log.info(documentID, tableName,
541                                                         "Ignoring unknown details LayoutItem of type " + libglomLayoutItem.get_part_type_name()
542                                                                         + ".");
543                                         continue;
544                                 }
545                         }
546
547                         layoutGroup.addItem(layoutItem);
548                 }
549
550                 return layoutGroup;
551         }
552
553         private LayoutItemPortal createLayoutItemPortalDTO(final String tableName,
554                         final org.glom.libglom.LayoutItem_Portal libglomLayoutItemPortal, final String localeID) {
555
556                 // Ignore LayoutItem_CalendarPortals for now:
557                 // https://bugzilla.gnome.org/show_bug.cgi?id=664273
558                 final LayoutItem_CalendarPortal liblglomLayoutItemCalendarPortal = LayoutItem_CalendarPortal
559                                 .cast_dynamic(libglomLayoutItemPortal);
560                 if (liblglomLayoutItemCalendarPortal != null)
561                         return null;
562
563                 final LayoutItemPortal layoutItemPortal = new LayoutItemPortal();
564                 final Relationship relationship = libglomLayoutItemPortal.get_relationship();
565                 if (relationship != null) {
566                         layoutItemPortal.setNavigationType(convertToGWTGlomNavigationType(libglomLayoutItemPortal
567                                         .get_navigation_type()));
568
569                         layoutItemPortal.setTitle(libglomLayoutItemPortal.get_title_used("", localeID)); // parent title not
570                                                                                                                                                                                                 // relevant
571                         layoutItemPortal.setName(libglomLayoutItemPortal.get_relationship_name_used());
572                         layoutItemPortal.setTableName(relationship.get_from_table());
573                         layoutItemPortal.setFromField(relationship.get_from_field());
574
575                         // convert the portal layout items into LayoutItemField DTOs
576                         final LayoutItemVector layoutItemsVec = libglomLayoutItemPortal.get_items();
577                         long numItems = layoutItemsVec.size();
578                         for (int i = 0; i < numItems; i++) {
579                                 final org.glom.libglom.LayoutItem libglomLayoutItem = layoutItemsVec.get(i);
580
581                                 // TODO add support for other LayoutItems (Text, Image, Button etc.)
582                                 final LayoutItem_Field libglomLayoutItemField = LayoutItem_Field.cast_dynamic(libglomLayoutItem);
583                                 if (libglomLayoutItemField != null) {
584                                         // TODO EDITING If the relationship does not allow editing, then mark all these fields as
585                                         // non-editable. Check relationship.get_allow_edit() to see if it's editable.
586                                         layoutItemPortal.addItem(convertToGWTGlomLayoutItemField(libglomLayoutItemField, localeID, false));
587                                 } else {
588                                         Log.info(documentID, tableName, "Ignoring unknown related list LayoutItem of type "
589                                                         + libglomLayoutItem.get_part_type_name() + ".");
590                                         continue;
591                                 }
592                         }
593
594                         // get the primary key for the related list table
595                         final LayoutItem_Field layoutItemField = new LayoutItem_Field();
596                         final String toTableName = relationship.get_to_table();
597                         if (!StringUtils.isEmpty(toTableName)) {
598
599                                 // get the LayoutItem_Feild with details from its Field in the document
600                                 final List<Field> fields = document.get_table_fields(toTableName);
601                                 numItems = fields.size(); // reuse loop variable from above
602                                 for (int i = 0; i < numItems; i++) {
603                                         final Field field = fields.get(i);
604                                         // check the names to see if they're the same
605                                         if (field.get_primary_key()) {
606                                                 layoutItemField.set_full_field_details(field);
607                                                 layoutItemPortal.addItem(convertToGWTGlomLayoutItemField(layoutItemField, localeID, false));
608                                                 layoutItemPortal.setPrimaryKeyIndex(layoutItemPortal.getItems().size() - 1);
609                                                 layoutItemPortal.setHiddenPrimaryKey(true); // always hidden in portals
610                                                 break;
611                                         }
612                                 }
613                         }
614
615                         // Set whether or not the related list will need to show the navigation buttons.
616                         // This was ported from Glom: Box_Data_Portal::get_has_suitable_record_to_view_details()
617                         final StringBuffer navigationTableName = new StringBuffer();
618                         final LayoutItem_Field navigationRelationship = new LayoutItem_Field(); // Ignored.
619                         //TODO: libglomLayoutItemPortal.get_suitable_table_to_view_details(navigationTableName, navigationRelationship,
620                         //              document);
621                         layoutItemPortal.setAddNavigation(!StringUtils.isEmpty(navigationTableName.toString()));
622                 }
623
624                 // Note: An empty LayoutItemPortal is returned if relationship is null.
625                 return layoutItemPortal;
626         }
627
628         private GlomNumericFormat convertNumbericFormat(final NumericFormat libglomNumericFormat) {
629                 final GlomNumericFormat gnf = new GlomNumericFormat();
630                 gnf.setUseAltForegroundColourForNegatives(libglomNumericFormat.get_alt_foreground_color_for_negatives());
631                 gnf.setCurrencyCode(libglomNumericFormat.get_currency_symbol());
632                 gnf.setDecimalPlaces(Utils.safeLongToInt(libglomNumericFormat.get_decimal_places()));
633                 gnf.setDecimalPlacesRestricted(libglomNumericFormat.get_decimal_places_restricted());
634                 gnf.setUseThousandsSeparator(libglomNumericFormat.get_use_thousands_separator());
635                 return gnf;
636         }
637
638         private Formatting convertFormatting(final org.glom.libglom.Formatting libglomFormatting) {
639                 final Formatting formatting = new Formatting();
640
641                 // text colour
642                 final String foregroundColour = libglomFormatting.get_text_format_color_foreground();
643                 if (!StringUtils.isEmpty(foregroundColour))
644                         formatting.setTextFormatColourForeground(convertGdkColorToHtmlColour(foregroundColour));
645                 final String backgroundColour = libglomFormatting.get_text_format_color_background();
646                 if (!StringUtils.isEmpty(backgroundColour))
647                         formatting.setTextFormatColourBackground(convertGdkColorToHtmlColour(backgroundColour));
648
649                 // multiline
650                 if (libglomFormatting.get_text_format_multiline()) {
651                         formatting.setTextFormatMultilineHeightLines(Utils.safeLongToInt(libglomFormatting
652                                         .get_text_format_multiline_height_lines()));
653                 }
654
655                 return formatting;
656         }
657
658         private LayoutItemField convertToGWTGlomLayoutItemField(final LayoutItem_Field libglomLayoutItemField,
659                         final String localeID, final boolean forDetailsView) {
660                 final LayoutItemField layoutItemField = new LayoutItemField();
661
662                 // set type
663                 layoutItemField.setType(convertToGWTGlomFieldType(libglomLayoutItemField.get_glom_type()));
664
665                 // set title and name
666                 layoutItemField.setTitle(libglomLayoutItemField.get_title_or_name(localeID));
667                 layoutItemField.setName(libglomLayoutItemField.get_name());
668
669                 // convert formatting
670                 final org.glom.libglom.Formatting glomFormatting = libglomLayoutItemField.get_formatting_used();
671                 final Formatting formatting = convertFormatting(glomFormatting);
672
673                 // set horizontal alignment
674                 final org.glom.libglom.Formatting.HorizontalAlignment libglomHorizontalAlignment = libglomLayoutItemField
675                                 .get_formatting_used_horizontal_alignment(forDetailsView); // only returns LEFT or RIGHT
676                 Formatting.HorizontalAlignment horizontalAlignment;
677                 if (libglomHorizontalAlignment == org.glom.libglom.Formatting.HorizontalAlignment.HORIZONTAL_ALIGNMENT_LEFT) {
678                         horizontalAlignment = Formatting.HorizontalAlignment.HORIZONTAL_ALIGNMENT_LEFT;
679                 } else {
680                         horizontalAlignment = Formatting.HorizontalAlignment.HORIZONTAL_ALIGNMENT_RIGHT;
681                 }
682                 formatting.setHorizontalAlignment(horizontalAlignment);
683
684                 // create a GlomNumericFormat DTO for numeric values
685                 if (libglomLayoutItemField.get_glom_type() == org.glom.libglom.Field.glom_field_type.TYPE_NUMERIC) {
686                         formatting.setGlomNumericFormat(convertNumbericFormat(glomFormatting.get_numeric_format()));
687                 }
688                 layoutItemField.setFormatting(formatting);
689
690                 return layoutItemField;
691         }
692
693         /*
694          * This method converts a Field.glom_field_type to the equivalent ColumnInfo.FieldType. The need for this comes from
695          * the fact that the GWT FieldType classes can't be used with RPC and there's no easy way to use the java-libglom
696          * Field.glom_field_type enum with RPC. An enum identical to Formatting.glom_field_type is included in the
697          * ColumnInfo class.
698          */
699         private LayoutItemField.GlomFieldType convertToGWTGlomFieldType(final glom_field_type glom_field_type) {
700                 switch (glom_field_type) {
701                 case TYPE_BOOLEAN:
702                         return LayoutItemField.GlomFieldType.TYPE_BOOLEAN;
703                 case TYPE_DATE:
704                         return LayoutItemField.GlomFieldType.TYPE_DATE;
705                 case TYPE_IMAGE:
706                         return LayoutItemField.GlomFieldType.TYPE_IMAGE;
707                 case TYPE_NUMERIC:
708                         return LayoutItemField.GlomFieldType.TYPE_NUMERIC;
709                 case TYPE_TEXT:
710                         return LayoutItemField.GlomFieldType.TYPE_TEXT;
711                 case TYPE_TIME:
712                         return LayoutItemField.GlomFieldType.TYPE_TIME;
713                 case TYPE_INVALID:
714                         Log.info("Returning TYPE_INVALID.");
715                         return LayoutItemField.GlomFieldType.TYPE_INVALID;
716                 default:
717                         Log.error("Recieved a type that I don't know about: " + Field.glom_field_type.class.getName() + "."
718                                         + glom_field_type.toString() + ". Returning " + LayoutItemField.GlomFieldType.TYPE_INVALID.toString() + ".");
719                         return LayoutItemField.GlomFieldType.TYPE_INVALID;
720                 }
721         }
722
723         /*
724          * Converts a Gdk::Color (16-bits per channel) to an HTML colour (8-bits per channel) by discarding the least
725          * significant 8-bits in each channel.
726          */
727         private String convertGdkColorToHtmlColour(final String gdkColor) {
728                 if (gdkColor.length() == 13)
729                         return gdkColor.substring(0, 3) + gdkColor.substring(5, 7) + gdkColor.substring(9, 11);
730                 else if (gdkColor.length() == 7) {
731                         // This shouldn't happen but let's deal with it if it does.
732                         Log.warn(documentID,
733                                         "Expected a 13 character string but received a 7 character string. Returning received string.");
734                         return gdkColor;
735                 } else {
736                         Log.error("Did not receive a 13 or 7 character string. Returning black HTML colour code.");
737                         return "#000000";
738                 }
739         }
740
741         /*
742          * This method converts a LayoutItem_Portal.navigation_type from java-libglom to the equivalent
743          * LayoutItemPortal.NavigationType from Online Glom. This conversion is required because the LayoutItem_Portal class
744          * from java-libglom can't be used with GWT-RPC. An enum identical to LayoutItem_Portal.navigation_type from
745          * java-libglom is included in the LayoutItemPortal data transfer object.
746          */
747         private LayoutItemPortal.NavigationType convertToGWTGlomNavigationType(
748                         final LayoutItem_Portal.navigation_type navigationType) {
749                 switch (navigationType) {
750                 case NAVIGATION_NONE:
751                         return LayoutItemPortal.NavigationType.NAVIGATION_NONE;
752                 case NAVIGATION_AUTOMATIC:
753                         return LayoutItemPortal.NavigationType.NAVIGATION_AUTOMATIC;
754                 case NAVIGATION_SPECIFIC:
755                         return LayoutItemPortal.NavigationType.NAVIGATION_SPECIFIC;
756                 default:
757                         Log.error("Recieved an unknown NavigationType: " + LayoutItem_Portal.navigation_type.class.getName() + "."
758                                         + navigationType.toString() + ". Returning " + LayoutItemPortal.NavigationType.NAVIGATION_AUTOMATIC
759                                         + ".");
760                         return LayoutItemPortal.NavigationType.NAVIGATION_AUTOMATIC;
761                 }
762         }
763
764         /**
765          * Gets the table name to use when accessing the database and the document. This method guards against SQL injection
766          * attacks by returning the default table if the requested table is not in the database or if the table name has not
767          * been set.
768          * 
769          * @param tableName
770          *            The table name to validate.
771          * @return The table name to use.
772          */
773         private String getTableNameToUse(final String tableName) {
774                 if (StringUtils.isEmpty(tableName) || !document.get_table_is_known(tableName)) {
775                         return document.get_default_table();
776                 }
777                 return tableName;
778         }
779
780         /**
781          * @param tableName
782          * @param localeID2
783          * @return
784          */
785         public Reports getReports(final String tableName, final String localeID) {
786                 final Reports result = new Reports();
787
788                 final StringVector names = document.get_report_names(tableName);
789
790                 final int count = Utils.safeLongToInt(names.size());
791                 for (int i = 0; i < count; i++) {
792                         final String name = names.get(i);
793                         final Report report = document.get_report(tableName, name);
794                         if (report == null)
795                                 continue;
796
797                         final String title = report.get_title(localeID);
798                         result.addReport(name, title);
799                 }
800
801                 return result;
802         }
803 }