- Minor change to Schema.infer()

Author: JohannesJander

docs/creating-schemas.md

@@ -93,7 +93,7 @@ You can  infer a schema from
 - a URL List
 - mixed data types (CSV, JSON, etc.)
 
-If you have more than one CSV file, you can use `infer()` to check that all files have the same schema:
+If you have more than one CSV file, you can use `Schema.infer()` to check that all files have the same schema:
 
 ```java
 File testFile = getResourceFile("/testsuite-data/files/csv/1mb.csv");
@@ -103,9 +103,10 @@ List<File> fileList = Arrays.asList(testFile, testFile2);
 Schema schema = Schema.infer(fileList, StandardCharsets.UTF_8);
 ```
 
-If the CSV files have different headers, the `Schema.infer()` call will throw an Exception.
+If the CSV files have different headers, the `Schema.infer()` call will throw an Exception because there 
+is no common schema that can be inferred from the files.
 
-In case you want to infer a schema and then use the data, it can be helpful to not use the static `Schema.infer()` 
+In case you want to infer a schema from a file and then use the data, it can be helpful to not use the static `Schema.infer()` 
 method, but first create a `Table` instance and then infer the schema from it. 
 
 ```java

pom.xml

@@ -3,7 +3,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>io.frictionlessdata</groupId>
     <artifactId>tableschema-java</artifactId>
-    <version>0.9.5-SNAPSHOT</version>
+    <version>0.9.6-SNAPSHOT</version>
     <packaging>jar</packaging>
     <issueManagement>
         <url>https://github.com/frictionlessdata/tableschema-java/issues</url>

src/main/java/io/frictionlessdata/tableschema/Table.java

@@ -640,7 +640,7 @@ public void validate() throws TableValidationException, TableSchemaException {
      * for the Field in question. At the end, the best score so far is returned.
      *
      * This method iterates through the whole data set, which can be very costly for huge
-     * CSV/JSON files
+     * CSV/JSON files. In that case, use the {@link #inferSchema(int)} method to set a row limit
      *
      * For {@link BeanSchema}, the operation is much less costly, it is simply done via reflection
      * on the Bean class.
@@ -662,6 +662,8 @@ public Schema inferSchema() throws TypeInferringException{
      * For {@link BeanSchema}, the operation is simply done via reflection
      * on the Bean class, so the `rowLimit`does not have any effect.
      *
+     * @param rowLimit The max numer of rows to scan. Huge input files can take a considerable time to infer.
+     *
      * @return the created Schema
      *
      */

src/main/java/io/frictionlessdata/tableschema/schema/Schema.java

@@ -237,21 +237,45 @@ public static Schema infer(List<Object[]> data, String[] headers, int rowLimit)
      * (direct data, files, or URLs), creating tables from each source, and then inferring
      * schemas from those tables. All inferred schemas must be equal, otherwise an exception
      * is thrown.
+     * This method can incur a significant performance penalty for large data sets, in that case use the
+     * overloaded method with a row limit.
      *
      * @param data    Direct data source - can be a String containing table data or an ArrayNode
      *                containing JSON representation of table data. May be null if using file or URL sources.
-     * @param charset The character encoding to use when reading from URLs. Used for URL streams only.
-     * @return        The inferred Schema that is consistent across all provided data sources
+     * @param charset  The character encoding to use when reading from URLs. Used for URL streams only.
+     *
+     * @return         The inferred Schema that is consistent across all provided data sources
+     * @throws IllegalStateException if no valid data source is provided, if the data type is not supported,
+     *                              or if schemas inferred from different sources are not equal
+     * @throws RuntimeException     if an IOException occurs while reading from files or URLs
+     */
+    public static Schema infer(Object data, Charset charset) {
+        return infer(data, charset, -1);
+    }
+
+    /**
+     * Infers a table schema from various data sources.
+     *
+     * This method attempts to infer a schema by reading data from one or more sources
+     * (direct data, files, or URLs), creating tables from each source, and then inferring
+     * schemas from those tables. All inferred schemas must be equal, otherwise an exception
+     * is thrown.
+     *
+     * @param data    Direct data source - can be a String containing table data or an ArrayNode
+     *                containing JSON representation of table data. May be null if using file or URL sources.
+     * @param charset  The character encoding to use when reading from URLs. Used for URL streams only.
+     * @param rowLimit The max numer of rows to scan. Huge input files can take a considerable time    to infer.
+     * @return         The inferred Schema that is consistent across all provided data sources
      * @throws IllegalStateException if no valid data source is provided, if the data type is not supported,
      *                              or if schemas inferred from different sources are not equal
      * @throws RuntimeException     if an IOException occurs while reading from files or URLs
      */
     public static Schema infer(
             Object data,
-            Charset charset) {
+            Charset charset,
+            int rowLimit) {
         List<File> paths = new ArrayList<>();
         List<URL> urls = new ArrayList<>();
-        // Infer schema from data source
         List<String> s = new ArrayList<>();
         if (data != null) {
             if (data instanceof String) {
@@ -349,7 +373,7 @@ public static Schema infer(
         for (String str : s) {
             Table table = Table.fromSource(str);
             String[] headers = table.getHeaders();
-            Schema schema = table.inferSchema(headers, -1);
+            Schema schema = table.inferSchema(headers, rowLimit);
             schemas.add(schema);
         }
         Schema lastSchema = null;