11package io .frictionlessdata .datapackage .resource ;
22
3+ import com .fasterxml .jackson .annotation .JsonIgnore ;
34import com .fasterxml .jackson .databind .JsonNode ;
45import com .fasterxml .jackson .databind .node .ArrayNode ;
56import com .fasterxml .jackson .databind .node .ObjectNode ;
@@ -44,9 +45,26 @@ public interface Resource<T,C> {
4445
4546 String getJson ();
4647
48+ /**
49+ * Read all data from a Resource, each row as String arrays. This can be used for smaller datapackages,
50+ * but for huge or unknown sizes, reading via iterator is preferred, as this method loads all data into RAM.
51+ *
52+ * It can be configured to return table rows with relations to other data sources resolved
53+ *
54+ * The method uses Iterators provided by {@link Table} class, and is roughly implemented after
55+ * https://github.com/frictionlessdata/tableschema-py/blob/master/tableschema/table.py
56+ *
57+ * @param relations true: follow relations
58+ * @return A list of table rows.
59+ * @throws Exception if parsing the data fails
60+ *
61+ */
62+ @ JsonIgnore
63+ public List <String []> getData (boolean relations ) throws Exception ;
64+
4765 /**
4866 * Read all data from a Resource, each row as Map objects. This can be used for smaller datapackages,
49- * but for huge or unknown sizes, reading via iterator is preferred.
67+ * but for huge or unknown sizes, reading via iterator is preferred, as this method loads all data into RAM .
5068 *
5169 * The method returns Map<String,Object> where key is the header name, and val is the data.
5270 * It can be configured to return table rows with relations to other data sources resolved
@@ -62,14 +80,17 @@ public interface Resource<T,C> {
6280 List <Map <String , Object >> getMappedData (boolean relations ) throws Exception ;
6381
6482 /**
65- * Read all data from a Resource. This can be used for smaller datapackages, but for huge or unknown
66- * sizes, reading via iterator is preferred.
83+ * Most customizable method to retrieve all data in a Resource. Parameters match those in
84+ * {@link io.frictionlessdata.tableschema.Table#iterator(boolean, boolean, boolean, boolean)}.
85+ * This can be used for smaller datapackages, but for huge or unknown
86+ * sizes, reading via iterator is preferred, as this method loads all data into RAM.
6787 *
6888 * The method can be configured to return table rows as:
6989 * <ul>
7090 * <li>String arrays (parameter `cast` = false)</li>
7191 * <li>as Object arrays (parameter `cast` = true)</li>
72- * <li>as a Map<key,val> where key is the header name, and val is the data (parameter `keyed` = true)</li>
92+ * <li>as a Map<String,Object> where key is the header name, and val is
93+ * the data (parameter `keyed` = true)</li>
7394 * <li>in an "extended" form (parameter `extended` = true) that returns an Object array where the first entry
7495 * is the row number, the second is a String array holding the headers,
7596 * and the third is an Object array holding the row data.</li>
@@ -91,7 +112,8 @@ public interface Resource<T,C> {
91112
92113 /**
93114 * Read all data from a Resource. This can be used for smaller datapackages, but for huge or unknown
94- * sizes, reading via iterator is preferred. The method ignores relations.
115+ * sizes, reading via iterator is preferred, as this method loads all data into RAM.
116+ * The method ignores relations.
95117 *
96118 * Returns as a List of Java objects of the type `beanClass`. Under the hood, it uses a {@link TableIterator}
97119 * for reading based on a Java Bean class instead of a {@link io.frictionlessdata.tableschema.schema.Schema}.
@@ -124,23 +146,27 @@ public interface Resource<T,C> {
124146 void writeSchema (Path parentFilePath ) throws IOException ;
125147
126148 /**
127- * Returns an Iterator that returns rows as object-arrays
128- * @return Row iterator
149+ * Returns an Iterator that returns rows as object-arrays. Values in each column
150+ * are parsed and converted ("cast") to Java objects based on the Field definitions of the Schema.
151+ * @return Iterator returning table rows as Object Arrays
129152 * @throws Exception if parsing the data fails
130153 */
131154 Iterator <Object []> objectArrayIterator () throws Exception ;
132155
133156 /**
134- * Returns an Iterator that returns rows as object-arrays
135- * @return Row Iterator
157+ * Returns an Iterator that returns rows as object-arrays. Values in each column
158+ * are parsed and converted ("cast") to Java objects based on the Field definitions of the Schema.
159+ * @return Iterator returning table rows as Object Arrays
136160 * @throws Exception if parsing the data fails
137161 */
138162 Iterator <Object []> objectArrayIterator (boolean extended , boolean relations ) throws Exception ;
139163
140-
141164 /**
142- * Returns an Iterator that returns rows as a Map<key,val> where key is the header name, and val is the data
143- * @return Row Iterator
165+ * Returns an Iterator that returns rows as a Map<key,val> where key is the header name, and val is the data.
166+ * It can be configured to follow relations
167+ *
168+ * @param relations Whether references to other data sources get resolved
169+ * @return Iterator that returns rows as Maps.
144170 * @throws Exception if parsing the data fails
145171 */
146172 Iterator <Map <String , Object >> mappingIterator (boolean relations ) throws Exception ;
@@ -156,10 +182,12 @@ public interface Resource<T,C> {
156182 * @param relations follow relations to other data source
157183 */
158184 Iterator <C > beanIterator (Class <C > beanType , boolean relations )throws Exception ;
185+
159186 /**
160- * Returns an Iterator that returns rows as string-arrays
161- * @return Row Iterator
162- * @throws Exception if parsing the data fails
187+ * This method creates an Iterator that will return table rows as String arrays.
188+ * It therefore disregards the Schema set on the table. It does not follow relations.
189+ *
190+ * @return Iterator that returns rows as string arrays.
163191 */
164192 public Iterator <String []> stringArrayIterator () throws Exception ;
165193
0 commit comments