Skip to content

Commit 2357a6b

Browse files
AndreaCimminoArriagaAndreaCimminoArriaga
authored
Merge pull request #13 from AndreaCimminoArriaga/master
Release 0.2.0
2 parents f5f671d + a6d0673 commit 2357a6b

File tree

200 files changed

+10049
-3560
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

200 files changed

+10049
-3560
lines changed

‎README.md‎

Lines changed: 159 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,159 @@
1-
# Java API for Thing Descriptions of WoT (JDT)
1+
# Java API for Thing Descriptions of WoT (JDTs)
2+
[![Maven Central](https://img.shields.io/badge/Maven%20Central-v0.1.6-orange)](https://search.maven.org/search?q=g:%22es.upm.fi.oeg%22%20AND%20a:%22wot-jtd%22) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![GitHub stars](https://img.shields.io/github/stars/Naereen/StrapDown.js.svg?style=social&label=Star&maxAge=2592000)](https://github.com/oeg-upm/wot-jtd/stargazers)
3+
4+
The JDT is an ORM implementation of the current [Thing Description](https://www.w3.org/TR/wot-thing-description/) model standardised by the [W3C Web of Things group](https://www.w3.org/WoT/). The current features are:
5+
* Serialise:
6+
* Serialise any Thing Description as a Java Object, i.e., a JDT
7+
* Serialise a JDT from a JSON-LD framed document
8+
* Serialise a JDT from a set of RDF triples
9+
* Round trip-translation:
10+
* Translate from a JSON-LD framed document into a set of equivalent RDF triples
11+
* Translate a set of RDF triples into its equivalent JSON-LD framed document
12+
* Validation **(coming soon)**
13+
* Validate a JTD using [SHACL shapes](https://www.w3.org/TR/shacl/)
14+
* Validate a JTD using [JSON schema](https://json-schema.org/)
15+
* Validate a JTD according to the [restrictions specified in the standard](https://www.w3.org/TR/wot-thing-description/)
16+
17+
If you have any feedback or feature suggestion, please let us know posting an issue with the label <span style="color:#EFA914">**feedback**</span>
18+
19+
## Table of contents
20+
21+
* Installation
22+
* Model
23+
* Usage:
24+
* Serialisation of JTDs:
25+
* From JSON-LD framed document
26+
* From RDF triples
27+
* Deserialisation of JTDs:
28+
* To JSON-LD framed
29+
* To RDF triples
30+
* JDT validation:
31+
* Using SHACL shapes
32+
* Using JSON schema (**coming soon**)
33+
* Using restrictions in the model (**coming soon**)
34+
35+
36+
37+
## Installation:
38+
Import the JDTs library as a maven dependency, **be sure to specify the latest version**:
39+
40+
```
41+
<dependency>
42+
<groupId>es.upm.fi.oeg</groupId>
43+
<artifactId>wot-jtd</artifactId>
44+
<version>0.1.6</version>
45+
</dependency>
46+
```
47+
48+
Alternatively, the dependency can be installed manually. First, download the latest jar from the [releases section](), and then install the dependency as follows (**be sure to specify the latest version**):
49+
````
50+
mvn install:install-file -Dfile=wot-jtd.jar -DgroupId=es.upm.fi.oeg -DartifactId=wot-jtd -Dversion=0.1.6 -Dpackaging=jar
51+
````
52+
53+
Check our [Maven Central Repository page](https://search.maven.org/artifact/es.upm.fi.oeg/wot-jtd/0.1.6/jar) to discover other installation options like Gradle Groovy or Kotlin, Scala, and others.
54+
55+
## Model
56+
57+
The JDT library implement as Java objects the whole model, and its restrictions, defined in the [Thing Description standard](https://www.w3.org/TR/wot-thing-description/). The overview of the model is the following:
58+
59+
![Thing Description model](https://www.w3.org/TR/wot-thing-description/visualization/td.png)
60+
61+
62+
## Usage
63+
64+
### Serialisation of JTDs:
65+
66+
For the next examples, let's assume the following java variables containing the same Thing description:
67+
````
68+
String strJsonTD = "{ \"@context\": \"https://www.w3.org/2019/wot/td/v1\",\n" +
69+
" \"id\": \"urn:dev:ops:32473-WoTLamp-1234\",\n" +
70+
" \"title\": \"MyLampThing\",\n" +
71+
" \"securityDefinitions\": { \"nosec_sc\": { \"scheme\": \"nosec\" }},\n" +
72+
" \"security\": \"nosec_sc\",\n" +
73+
" \"properties\": {\n" +
74+
" \"status\": {\n" +
75+
" \"type\": \"string\",\n" +
76+
" \"forms\": [{\"href\": \"https://mylamp.example.com/status\"}]\n" +
77+
" }\n" +
78+
" }\n" +
79+
"}";
80+
````
81+
82+
````
83+
Model modelTD = ModelFactory.createDefaultModel();
84+
String strRdfTD = "@prefix dc: <http://purl.org/dc/terms/> .\n" +
85+
"@prefix td: <https://www.w3.org/2019/wot/td#> .\n" +
86+
"@prefix jsonschema: <https://www.w3.org/2019/wot/json-schema#> .\n" +
87+
"@prefix hctl: <https://www.w3.org/2019/wot/hypermedia#> .\n" +
88+
"\n" +
89+
"<urn:dev:ops:32473-WoTLamp-1234>\n" +
90+
" dc:title \"MyLampThing\" ;\n" +
91+
" td:hasPropertyAffordance [\n" +
92+
" a <https://www.w3.org/2019/wot/json-schema#StringSchema> ;\n" +
93+
" jsonschema:propertyName \"status\" ;\n" +
94+
" td:hasForm [ hctl:hasTarget <https://mylamp.example.com/status> ]\n" +
95+
" ] ;\n" +
96+
" td:hasSecurityConfiguration <https://json-ld.org/playground/nosec_sc> ;\n" +
97+
" td:securityDefinitions [ td:scheme \"nosec\" ] .";
98+
99+
##### Read the string variable into the jena model
100+
modelTD.read(new ByteArrayInputStream(strRdfTD.getBytes()), null, "Turtle");
101+
````
102+
103+
104+
105+
The following serialisation operations consists of building a JTD object Thing from either a JSON-LD framed representation or a set of RDF triples.
106+
##### From JSON-LD framed document
107+
108+
````
109+
JsonObject jsonTD = JTD.parseJson(strJsonTD);
110+
Thing thing = Thing.fromJson(jsonTD);
111+
thing = (Thing) JTD.instantiateFromJson(jsonTD, Thing.class); # Alternativelly
112+
````
113+
Notice that using the method `JTD.instantiateFromJson(jsonTD, Thing.class)` any other class from the model can be serialised.
114+
115+
##### From RDF triples
116+
In order to build a JTD object from a set of RDF triples there are two main methods:
117+
##### A) Build a list of JTDs in case that the triples contain more than one Thing resource.
118+
`````
119+
List<Thing> things = fromRDF(modelTD)
120+
`````
121+
##### B) Build a unique JTDs providing the RDF resource URI.
122+
`````
123+
Thing thing = fromRDF(modelTD, "urn:dev:ops:32473-WoTLamp-1234")
124+
`````
125+
126+
### Deserialisation of JTDs:
127+
128+
##### To JSON-LD framed
129+
````
130+
JsonObject jsonTD = thing.toJson()
131+
jsonTD = JTD.toJson(thing) # Alternativelly
132+
````
133+
Notice that using the method `JTD.toJson(thing)` any other class from the model can be deserialised.
134+
135+
##### To RDF triples
136+
137+
````
138+
Model modelTD = JTD.toRDF(thing)
139+
# Alternativelly
140+
JsonObject jsonTD = thing.toJson()
141+
modelTD = JTD.toRDF(jsonTD)
142+
````
143+
144+
Notice that using the method alternative `JTD.toRDF(jsonTD)` there is actually no need to serialise the JSON-LD framed `jsonTD` as a Java object, it can be directly translated into RDF.
145+
146+
147+
### JDT validation
148+
149+
##### Using SHACL shapes
150+
Currently, the Web of Things provides [an official SHACL shape document](https://github.com/w3c/wot-thing-description/blob/main/validation/td-validation.ttl) for validating Thing Descriptions. This shape, or any other, can be used to validate a JTD Thing as follows:
151+
152+
````
153+
String shapesURI = "https://raw.githubusercontent.com/w3c/wot-thing-description/main/validation/td-validation.ttl"
154+
Model shapesGraph = RDFDataMgr.loadModel(shapesURI, Lang.TURTLE);
155+
ValidationReport shapeReport = JTD.validateWithShape(thing, shapesGraph);
156+
````
157+
158+
##### Using JSON schema (*comming soon*)
159+
##### Using restrictions in the model (*comming soon*)

‎pom.xml‎

Lines changed: 109 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<modelVersion>4.0.0</modelVersion>
33
<groupId>es.upm.fi.oeg</groupId>
44
<artifactId>wot-jtd</artifactId>
5-
<version>0.1.5-SNAPSHOT</version>
5+
<version>0.2.0</version>
66
<url>https://oeg-upm.github.io/wot-jtd</url>
77
<name>Java Thing Description API</name>
88
<description>This API aims at assisting developers for handling WoT Thing Descriptions, providing special support for RDF.</description>
@@ -48,9 +48,96 @@
4848
</repository>
4949
</distributionManagement>
5050

51-
<build>
52-
53-
</build>
51+
<repositories>
52+
<repository>
53+
<id>jitpack.io</id>
54+
<url>https://jitpack.io</url>
55+
</repository>
56+
</repositories>
57+
58+
<build>
59+
<plugins>
60+
<plugin>
61+
<groupId>org.sonatype.plugins</groupId>
62+
<artifactId>nexus-staging-maven-plugin</artifactId>
63+
<version>1.6.7</version>
64+
<extensions>true</extensions>
65+
<configuration>
66+
<serverId>ossrh</serverId>
67+
<nexusUrl>https://oss.sonatype.org/</nexusUrl>
68+
<autoReleaseAfterClose>true</autoReleaseAfterClose>
69+
</configuration>
70+
</plugin>
71+
<plugin>
72+
<groupId>org.apache.maven.plugins</groupId>
73+
<artifactId>maven-release-plugin</artifactId>
74+
<version>2.5.3</version>
75+
<configuration>
76+
<autoVersionSubmodules>true</autoVersionSubmodules>
77+
<useReleaseProfile>false</useReleaseProfile>
78+
<releaseProfiles>release</releaseProfiles>
79+
<goals>deploy</goals>
80+
</configuration>
81+
</plugin>
82+
<!-- Javadoc and sources attached -->
83+
<plugin>
84+
<groupId>org.apache.maven.plugins</groupId>
85+
<artifactId>maven-source-plugin</artifactId>
86+
<version>2.2.1</version>
87+
<executions>
88+
<execution>
89+
<id>attach-sources</id>
90+
<goals>
91+
<goal>jar-no-fork</goal>
92+
</goals>
93+
</execution>
94+
</executions>
95+
</plugin>
96+
<plugin>
97+
<groupId>org.apache.maven.plugins</groupId>
98+
<artifactId>maven-javadoc-plugin</artifactId>
99+
<version>2.9.1</version>
100+
<configuration>
101+
<source>8</source>
102+
<detectJavaApiLink>false</detectJavaApiLink>
103+
</configuration>
104+
<executions>
105+
<execution>
106+
<id>attach-javadocs</id>
107+
<goals>
108+
<goal>jar</goal>
109+
</goals>
110+
</execution>
111+
</executions>
112+
</plugin>
113+
<!-- GPG signing -->
114+
<plugin>
115+
<groupId>org.apache.maven.plugins</groupId>
116+
<artifactId>maven-gpg-plugin</artifactId>
117+
<version>1.5</version>
118+
<executions>
119+
<execution>
120+
<id>sign-artifacts</id>
121+
<phase>verify</phase>
122+
<goals>
123+
<goal>sign</goal>
124+
</goals>
125+
</execution>
126+
</executions>
127+
</plugin>
128+
<plugin>
129+
<groupId>org.sonatype.plugins</groupId>
130+
<artifactId>nexus-staging-maven-plugin</artifactId>
131+
<version>1.6.7</version>
132+
<extensions>true</extensions>
133+
<configuration>
134+
<serverId>ossrh</serverId>
135+
<nexusUrl>https://oss.sonatype.org/</nexusUrl>
136+
<autoReleaseAfterClose>true</autoReleaseAfterClose>
137+
</configuration>
138+
</plugin>
139+
</plugins>
140+
</build>
54141

55142
<dependencies>
56143
<!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-core -->
@@ -77,6 +164,8 @@
77164
<artifactId>hibernate-validator</artifactId>
78165
<version>6.0.13.Final</version>
79166
</dependency>
167+
168+
80169
<dependency>
81170
<groupId>org.glassfish</groupId>
82171
<artifactId>javax.el</artifactId>
@@ -107,18 +196,20 @@
107196
<artifactId>commons-logging</artifactId>
108197
<version>1.2</version>
109198
</dependency>
110-
111-
<!-- JSON-LD -->
112-
<dependency>
113-
<groupId>com.apicatalog</groupId>
114-
<artifactId>titanium-json-ld</artifactId>
115-
<version>1.0.0</version>
199+
<!-- https://mvnrepository.com/artifact/org.apache.commons/commons-lang3 -->
200+
<dependency>
201+
<groupId>org.apache.commons</groupId>
202+
<artifactId>commons-lang3</artifactId>
203+
<version>3.11</version>
116204
</dependency>
117-
<dependency>
118-
<groupId>org.glassfish</groupId>
119-
<artifactId>jakarta.json</artifactId>
120-
<version>2.0.0</version>
121-
</dependency>
205+
206+
<!-- Json schema -->
207+
<dependency>
208+
<groupId>com.github.everit-org.json-schema</groupId>
209+
<artifactId>org.everit.json.schema</artifactId>
210+
<version>1.12.2</version>
211+
</dependency>
212+
122213
<!-- jena -->
123214
<!-- https://mvnrepository.com/artifact/org.apache.jena/apache-jena-libs -->
124215
<dependency>
@@ -128,6 +219,8 @@
128219
<type>pom</type>
129220
</dependency>
130221

222+
223+
131224
<!-- https://mvnrepository.com/artifact/junit/junit -->
132225
<dependency>
133226
<groupId>junit</groupId>
@@ -136,6 +229,7 @@
136229
<scope>test</scope>
137230
</dependency>
138231

232+
139233
</dependencies>
140234

141235

‎src/main/java/kehio/annotations/RdfContainer.java‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
package kehio.annotations;
2+
3+
import java.lang.annotation.ElementType;
4+
import java.lang.annotation.Inherited;
5+
import java.lang.annotation.Retention;
6+
import java.lang.annotation.RetentionPolicy;
7+
import java.lang.annotation.Target;
8+
9+
@Retention(RetentionPolicy.RUNTIME)
10+
@Target(ElementType.FIELD)
11+
@Inherited
12+
public @interface RdfContainer {
13+
String[] ignore() default {};
14+
RdfUrlMap[] prefixes() default {};
15+
RdfUrlMap[] aliases(); // if property is present in alias, overrides the ignore properties
16+
String[] identifiers();
17+
}

‎src/main/java/kehio/annotations/RdfDatatype.java‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
package kehio.annotations;
2+
3+
import java.lang.annotation.ElementType;
4+
import java.lang.annotation.Inherited;
5+
import java.lang.annotation.Retention;
6+
import java.lang.annotation.RetentionPolicy;
7+
import java.lang.annotation.Target;
8+
9+
@Retention(RetentionPolicy.RUNTIME)
10+
@Target(ElementType.FIELD)
11+
@Inherited
12+
public @interface RdfDatatype {
13+
String value() default "";
14+
String lang() default "";
15+
String datatype() default "";
16+
boolean sinkLang() default false;
17+
boolean sinkDatatype() default false;
18+
}
19+

‎src/main/java/wot/jtd/annotations/RdfObjectProperty.java‎ renamed to ‎src/main/java/kehio/annotations/RdfDatatypeGroup.java‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
package wot.jtd.annotations;
1+
package kehio.annotations;
22

33
import java.lang.annotation.ElementType;
44
import java.lang.annotation.Inherited;
@@ -9,6 +9,8 @@
99
@Retention(RetentionPolicy.RUNTIME)
1010
@Target(ElementType.FIELD)
1111
@Inherited
12-
public @interface RdfObjectProperty {
12+
public @interface RdfDatatypeGroup {
1313
String value() default "";
14+
boolean byLang() default false;
15+
boolean byDatatype() default false;
1416
}

0 commit comments

Comments
 (0)