Author: jpz6311whu
Date: Fri Aug 15 06:51:50 2014
New Revision: 1618109
URL: http://svn.apache.org/r1618109
Log:
JENA-625, improved documentation
Modified:
jena/site/trunk/content/documentation/csv/design.mdtext
jena/site/trunk/content/documentation/csv/get_started.mdtext
Modified: jena/site/trunk/content/documentation/csv/design.mdtext
URL:
http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/csv/design.mdtext?rev=1618109&r1=1618108&r2=1618109&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/csv/design.mdtext (original)
+++ jena/site/trunk/content/documentation/csv/design.mdtext Fri Aug 15 06:51:50
2014
@@ -50,7 +50,7 @@ Its constructor takes a CSV file path as
For CSV to RDF mapping, we establish some basic principles:
-### Single-Value and Regular-Shaped CSV only
+### Single-Value and Regular-Shaped CSV Only
In the [CSV-WG](https://www.w3.org/2013/csvw/wiki/Main_Page), it looks like
duplicate column names are not going to be supported. Therefore, we just
consider parsing single-valued CSV tables.
There is the current editor working [draft](http://w3c.github.io/csvw/syntax/)
from the CSV on the Web Working Group, which is defining a more regular data
out of CSV.
@@ -67,10 +67,19 @@ It's not necessary to have a defined pri
### Data Type for Typed Literal
All the values in CSV are parsed as strings line by line. As a better option
for the user to turn on, a dynamic choice which is a posh way of saying attempt
to parse it as an integer (or decimal, double, date) and if it passes, it's an
integer (or decimal, double, date).
+Note that for the current release, all of the numbers are parsed as `double`,
and `date` is not supported yet.
### File Path as Namespace
RDF requires that the subjects and the predicates are URIs. We need to pass in
the namespaces (or just the default namespaces) to make URIs by combining the
namespaces with the values in CSV.
We donât have metadata of the namespaces for the columns, But subjects can
be blank nodes which is useful because each row is then a new blank node. For
predicates, suppose the URL of the CSV file is `file:///c:/town.csv`, then the
columns can be `<file:///c:/town.csv#Town>` and
`<file:///c:/town.csv#Population>`, as is showed in the illustration.
+### First Line of Table Header Needed as Predicates
+
+The first line of the CSV file must be the table header. The columns of the
first line are parsed as the predicates of the RDF triples. The RDF triple data
are parsed starting from the second line.
+
+### UTF-8 Encoded Only
+
+The CSV files must be UTF-8 encoded. If your CSV files are using Western
European encodings, please change the encoding before using CSV PropertyTable.
+
Modified: jena/site/trunk/content/documentation/csv/get_started.mdtext
URL:
http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/csv/get_started.mdtext?rev=1618109&r1=1618108&r2=1618109&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/csv/get_started.mdtext (original)
+++ jena/site/trunk/content/documentation/csv/get_started.mdtext Fri Aug 15
06:51:50 2014
@@ -1,9 +1,30 @@
Title: CSV PropertyTable - Get Started
+## Using CSV PropertyTable with Apache Maven
+
+See ["Using Jena with Apache
Maven"](http://jena.apache.org/download/maven.html) for full details.
+
+ <dependency>
+ <groupId>org.apache.jena</groupId>
+ <artifactId>jena-csv</artifactId>
+ <version>X.Y.Z</version>
+ </dependency>
+
## Using CSV PropertyTable from Java through the API
-For the users,
[GraphCSV](https://svn.apache.org/repos/asf/jena/Experimental/jena-csv/src/main/java/org/apache/jena/propertytable/impl/GraphCSV.java)
is the only class required to run CSV PropertyTable.
-GraphCSV wrappers a CSV file as a Graph, which makes a Model for SPARQL query:
+In order to switch on CSV PropertyTable, it's required to register `LangCSV`
into [Jena RIOT](http://jena.apache.org/documentation/io/), through a simple
method call:
+
+ import org.apache.jena.propertytable.lang.LangCSV;
+ ...
+ LangCSV.register();
+
+It's a static method call of registration, which needs to be run just one time
for an application before using CSV PropertyTable (e.g. during the
initialization phase).
+
+Once registered, CSV PropertyTable provides 2 ways for the users to play with
(i.e. GraphCSV and RIOT):
+
+### GraphCSV
+
+[GraphCSV](https://svn.apache.org/repos/asf/jena/Experimental/jena-csv/src/main/java/org/apache/jena/propertytable/graph/GraphCSV.java)
wrappers a CSV file as a Graph, which makes a Model for SPARQL query:
Model model = ModelFactory.createModelForGraph(new GraphCSV("data.csv")) ;
QueryExecution qExec = QueryExecutionFactory.create(query, model) ;
@@ -19,9 +40,25 @@ or for multiple CSV files and/or other R
dataset.addNamedModel("http://example/other";, other) ;
... normal SPARQL execution ...
-You can also find the full examples from
[GraphCSVTest](https://svn.apache.org/repos/asf/jena/Experimental/jena-csv/src/test/java/org/apache/jena/propertytable/impl/GraphCSVTest.java).
+You can also find the full examples from
[GraphCSVTest](https://svn.apache.org/repos/asf/jena/Experimental/jena-csv/src/test/java/org/apache/jena/propertytable/graph/GraphCSVTest.java).
+
+In short, for Jena ARQ, a CSV table is actually a Graph (i.e. GraphCSV),
without any differences from other types of Graphs when using it from the Jena
ARQ API.
+
+### RIOT
+
+When LangCSV is registered into RIOT, CSV PropertyTable adds a new RDF syntax
of '.csv' with the content type of "text/csv".
+You can read ".csv" files into Model following the standard RIOT usages:
+
+ // Usage 1: Direct reading through Model
+ Model model_1 = ModelFactory.createDefaultModel()
+ model.read("test.csv") ;
+
+ // Usage 2: Reading using RDFDataMgr
+ Model model_2 = RDFDataMgr.loadModel("test.csv") ;
+
+For more information, see [Reading RDF in Apache
Jena](http://jena.apache.org/documentation/io/rdf-input.html).
-In short, for Jena ARP, a CSV table is actually a Graph (i.e. GraphCSV),
without any differences from other types of Graphs when using it from the Jena
ARQ API.
+Note that, the requirements for the CSV files are listed in the documentation
of [Design](design.html). CSV PropertyTable only supports single-Value,
regular-Shaped, table-headed and UTF-8-encoded CSV files.
## Command Line Tool
