Author: jpz6311whu
Date: Sun Aug 3 09:43:18 2014
New Revision: 1615398
URL: http://svn.apache.org/r1615398
Log:
update Design Documentation for CSV PropertyTable [JENA 625]
Modified:
jena/site/trunk/content/documentation/csv/design.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=1615398&r1=1615397&r2=1615398&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/csv/design.mdtext (original)
+++ jena/site/trunk/content/documentation/csv/design.mdtext Sun Aug 3 09:43:18
2014
@@ -2,7 +2,7 @@ Title: CSV PropertyTable - Design
## Architecture
-The architecture of jena-csv mainly involves 2 components:
+The architecture of CSV PropertyTable mainly involves 2 components:
-
[PropertyTable](https://svn.apache.org/repos/asf/jena/Experimental/jena-csv/src/main/java/org/apache/jena/propertytable/PropertyTable.java)
-
[GraphPropertyTable](https://svn.apache.org/repos/asf/jena/Experimental/jena-csv/src/main/java/org/apache/jena/propertytable/impl/GraphPropertyTable.java)
@@ -25,6 +25,14 @@ Each [Column](https://svn.apache.org/rep
Each
[Row](https://svn.apache.org/repos/asf/jena/Experimental/jena-csv/src/main/java/org/apache/jena/propertytable/Row.java)
of the `PropertyTable` has an unique rowKey `Node` of the subject (or s for
short).
You can use `getColumn()` to get the `Column` by its columnKey `Node` of the
predicate, while `getRow()` for `Row`.
+A `PropertyTable` should be constructed in this workflow (in order):
+
+1. Create `Columns` using `PropertyTable.createColumn()` for each `Column`
of the `PropertyTable`
+2. Create `Rows` using `PropertyTable.createRow()` for each `Row` of the
`PropertyTable`
+3. For each `Row' created, set a value (`Node`) at the specified `Column`,
by calling `Row.setValue()`
+
+Once a `PropertyTable` is built, tabular data within can be accessed by the
API of `PropertyTable.getMatchingRows()`, `PropertyTable.getColumnValues()`,
etc.
+
### GraphPropertyTable
`GraphPropertyTable` implements the
[Graph](https://svn.apache.org/repos/asf/jena/trunk/jena-core/src/main/java/com/hp/hpl/jena/graph/Graph.java)
interface (read-only) over a `PropertyTable`.
@@ -32,10 +40,37 @@ This is subclass from [GraphBase](https:
The `graphBaseFind()` method can choose the access route based on the find
arguments.
It holds/wraps an reference of the `PropertyTable` instance, so that such a
graph can be treated in a more table-like fashion.
-Note that, both `PropertyTable` and `GraphPropertyTable` are *NOT* restricted
to CSV data.
+**Note:** Both `PropertyTable` and `GraphPropertyTable` are *NOT* restricted
to CSV data.
They are supposed to be compatible with any table-like data sources, such as
relational databases, Microsoft Excel, etc.
### GraphCSV
[GraphCSV](https://svn.apache.org/repos/asf/jena/Experimental/jena-csv/src/main/java/org/apache/jena/propertytable/impl/GraphCSV.java)
is a sub class of GraphPropertyTable aiming at CSV data.
-Its constructor takes a CSV file path as the parameter and makes a
`GraphPropertyTable` through parsing the file.
+Its constructor takes a CSV file path as the parameter, parse the file using a
CSV Parser, and makes a `PropertyTable` through `PropertyTableBuilder`.
+
+For CSV to RDF mapping, we establish some basic principles:
+
+#### 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.
+This is the target for the CSV work of GraphCSV: tabular regular-shaped CSV;
not arbitrary, irregularly shaped CSV.
+
+#### No Additional CSV Metadata
+
+A CSV file with no additional metadata is directly mapped to RDF, which makes
a simpler case compared to SQL-to-RDF work.
+It's not necessary to have a defined primary column, similar to the primary
key of database. The subject of the triple can be generated through one of:
+
+1. The triples for each row have a blank node for the subject, e.g.
something like the illustration
+2. The triples for row N have a subject URI which is `<FILE#_N>`.
+
+#### 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).
+
+#### 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.
+
+
