Skip to content

Commit 61fd863

Browse files
PfeilPfeil
committed
docs: move quickstart to LearnByExampleTest so it is always tested properly
1 parent 3eec23d commit 61fd863

3 files changed

Lines changed: 435 additions & 153 deletions

File tree

‎README.md‎

Lines changed: 17 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ and avoiding crates which do not fully comply to the specification, at the same
1313

1414
- [Instructions for your build manager (e.g., Gradle, Maven, etc.)](https://central.sonatype.com/artifact/edu.kit.datamanager/ro-crate-java)
1515
- [Quick-Start](#quick-start)
16+
- [JavaDoc Documentation](https://javadoc.io/doc/edu.kit.datamanager/ro-crate-java)
1617
- [Related Publications](https://publikationen.bibliothek.kit.edu/publikationslisten/get.php?referencing=all&external_publications=kit&lang=de&format=html&style=kit-3lines-title_b-authors-other&consider_suborganizations=true&order=desc%20year&contributors=%5B%5B%5B%5D%2C%5B%22p20751.105%22%5D%5D%5D&title_contains=crate)
1718

1819
## Build the library / documentation
@@ -37,162 +38,27 @@ On Windows, replace `./gradlew` with `gradlew.bat`.
3738

3839
## Quick-start
3940

40-
> Note: We have a [module with well-described unit tests to guide you](src/test/java/edu/kit/datamanager/ro_crate/examples/), describing how to generate official examples extracted from the specification.
41-
> Specifically, the examples for the [specification in version 1.1](https://www.researchobject.org/ro-crate/1.1/) are available in [ExamplesOfSpecificationV1p1Test.java](src/test/java/edu/kit/datamanager/ro_crate/examples/ExamplesOfSpecificationV1p1Test.java).
41+
` ro-crate-java` makes use of the builder pattern to guide the user to create a valid RO-Crate, similar to:
4242

43-
### Example for a basic crate from [RO-Crate website](https://www.researchobject.org/ro-crate/1.1/root-data-entity.html#ro-crate-metadata-file-descriptor)
4443
```java
45-
RoCrate roCrate = new RoCrateBuilder("name", "description", "datePublished", "licenseIdentifier").build();
46-
```
47-
48-
### Example adding a File (Data Entity) and a context pair
49-
```java
50-
RoCrate roCrate = new RoCrateBuilder("name", "description", "datePublished", "licenseIdentifier")
51-
.addValuePairToContext("Station", "www.station.com")
52-
.addUrlToContext("contextUrl")
44+
RoCrate myFirstCrate = STARTER_CRATE
5345
.addDataEntity(
54-
new FileEntity.FileEntityBuilder()
55-
.setId("survey-responses-2019.csv")
56-
.addProperty("name", "Survey responses")
57-
.addProperty("contentSize", "26452")
58-
.addProperty("encodingFormat", "text/csv")
59-
.build()
46+
new FileEntity.FileEntityBuilder()
47+
.setId("path/within/crate/survey-responses-2019.csv")
48+
.setLocation(Paths.get("path/to/current/location/experiment.csv"))
49+
.addProperty("name", "Survey responses")
50+
.addProperty("contentSize", "26452")
51+
.addProperty("encodingFormat", "text/csv")
52+
.build()
6053
)
61-
.addDataEntity(...)
62-
...
63-
.addContextualEntity(...)
64-
...
65-
.build();
66-
```
67-
68-
The library currently comes with three specialized DataEntities:
69-
70-
1. `DataSetEntity`
71-
2. `FileEntity` (used in the example above)
72-
3. `WorkflowEntity`
73-
74-
If another type of `DataEntity` is required, the base class `DataEntity` can be used. Example:
75-
```java
76-
new DataEntity.DataEntityBuilder()
77-
.addType("CreativeWork")
78-
.setId("ID")
79-
.addProperty("property from schema.org/Creativework", "value")
80-
.build();
81-
```
82-
Note that here you are supposed to add the type of your `DataEntity` because it is not known.
83-
84-
A `DataEntity` and its subclasses can have a file located on the web. Example:
85-
86-
Example adding file:
87-
```java
88-
new FileEntity.FileEntityBuilder()
89-
.addContent(URI.create("https://github.com/kit-data-manager/ro-crate-java/issues/5"))
90-
.addProperty("description", "my new file that I added")
91-
.build();
92-
```
93-
94-
A `DataEntity` and its subclasses can have a local file associated with them,
95-
instead of one located on the web (which link is the ID of the data entity). Example:
96-
97-
Example adding file:
98-
```java
99-
new FileEntity.FileEntityBuilder()
100-
.addContent(Paths.get("file"), "new_file.txt")
101-
.addProperty("description", "my new local file that I added")
102-
.build();
103-
```
104-
105-
### Contextual Entities
106-
107-
Contextual entities cannot be associated with a file (they are pure metadata).
108-
109-
To add a contextual entity to a crate you use the function `.addContextualEntity(ContextualEntity entity)`.
110-
Some types of derived/specializes entities are:
111-
1. `OrganizationEntity`
112-
2. `PersonEntity`
113-
3. `PlaceEntity`
114-
115-
If you need another type of contextual entity, use the base class `ContextualEntity`.
116-
117-
The library provides a way to automatically create contextual entities from external providers. Currently, support for [ORCID](https://orcid.org/) and [ROR](https://ror.org/) is implemented. Example:
118-
```java
119-
PersonEntity person = ORCIDProvider.getPerson("https://orcid.org/*")
120-
OrganizationEntity organization = RORProvider.getOrganization("https://ror.org/*");
121-
```
122-
123-
### Writing Crate to folder, zip file, or zip stream
124-
125-
Writing to folder:
126-
```java
127-
RoCrateWriter folderRoCrateWriter = new RoCrateWriter(new FolderWriter());
128-
folderRoCrateWriter.save(roCrate, "destinationFolder");
129-
```
130-
131-
Writing to zip file:
132-
```java
133-
RoCrateWriter roCrateZipWriter = new RoCrateWriter(new ZipWriter());
134-
roCrateZipWriter.save(roCrate, "destinationFolder");
135-
```
136-
137-
Writing to zip stream:
138-
```java
139-
RoCrateWriter roCrateZipStreamWriter = new RoCrateWriter(new ZipStreamWriter());
140-
roCrateZipStreamWriter.save(roCrate, outputStream);
141-
```
142-
143-
More writing strategies can be implemented, if required.
144-
145-
### Reading / importing Crate from folder or zip
146-
147-
Reading from folder:
148-
```java
149-
RoCrateReader roCrateFolderReader = new RoCrateReader(new FolderReader());
150-
RoCrate res = roCrateFolderReader.readCrate("destinationFolder");
151-
```
152-
153-
Reading from zip file:
154-
```java
155-
RoCrateReader roCrateFolderReader = new RoCrateReader(new ZipReader());
156-
RoCrate crate = roCrateFolderReader.readCrate("sourceZipFile");
157-
```
158-
159-
Reading from zip stream:
160-
```java
161-
RoCrateReader roCrateFolderReader = new RoCrateReader(new ZipStreamReader());
162-
RoCrate crate = roCrateFolderReader.readCrate(inputStream);
163-
```
164-
165-
### RO-Crate Website (HTML preview file)
166-
ro-crate-java offers tree different kinds of previews:
167-
168-
* AutomaticPreview: Uses third-party library [ro-crate-html-js](https://www.npmjs.com/package/ro-crate-html-js), which must be installed separately.
169-
* CustomPreview: Pure Java-based preview using an included template processed by the FreeMarker template engine. At the same time, CustomPreview is the fallback for AutomaticPreview if ro-crate-html-js is not installed.
170-
* StaticPreview: Allows to provide a static HTML page (including additional dependencies, e.g., CSS, JS) which is then shipped with the RO-Crate.
171-
172-
When creating a new RO-Crate using the builder, the default setting is to use CustomPreview. If you want to change this behaviour, thr preview method is set as follows:
173-
174-
```java
175-
RoCrate roCrate = new RoCrateBuilder("name", "description", "datePublished", "licenseIdentifier")
176-
.setPreview(new AutomaticPreview())
54+
.addDataEntity(/*...*/)
55+
.addContextualEntity(/*...*/)
17756
.build();
17857
```
17958

180-
Keep in mind that, if you want to use AutomaticPreview, you have to install ro-crate-html-js via `npm install --global ro-crate-html-js` first.
181-
182-
For StaticPreview, the constructor is a bit different, such that it looks as follows:
59+
A built or imported crate can of course also be modified afterwards. Take a look at our further documentation:
18360

184-
```java
185-
File pathToMainPreviewHtml = new File("localPath");
186-
File pathToAdditionalFiles = new File("localFolder");
187-
RoCrate roCrate = new RoCrateBuilder("name", "description", "datePublished", "licenseIdentifier")
188-
.setPreview(new StaticPreview(pathToMainPreviewHtml, pathToAdditionalFiles))
189-
.build();
190-
```
191-
192-
### RO-Crate validation (machine-readable crate profiles)
193-
Right now, the only implemented way of validating a RO-crate is to use a [JSON-Schema](https://json-schema.org/) that the crates metadata JSON file should match. JSON-Schema is an established standard and therefore a good choice for a crate profile. Example:
194-
195-
```java
196-
Validator validator = new Validator(new JsonSchemaValidation("./schema.json"));
197-
boolean valid = validator.validate(crate);
198-
```
61+
- **There is a well-documented example-driven guide in [LearnByExampleTest.java](src/test/java/edu/kit/datamanager/ro_crate/examples/LearnByExampleTest.java) to help you get started.**
62+
- You may also be interested in the examples we extracted from the [specification in version 1.1](https://www.researchobject.org/ro-crate/1.1/), which are available in [ExamplesOfSpecificationV1p1Test.java](src/test/java/edu/kit/datamanager/ro_crate/examples/ExamplesOfSpecificationV1p1Test.java).
63+
- There is a [module with all well-described guiding tests](src/test/java/edu/kit/datamanager/ro_crate/examples/) available.
64+
- The [JavaDoc Documentation](https://javadoc.io/doc/edu.kit.datamanager/ro-crate-java) is also available online.

‎src/main/java/edu/kit/datamanager/ro_crate/preview/StaticPreview.java‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
import edu.kit.datamanager.ro_crate.util.ZipUtil;
44
import java.io.File;
55
import java.io.IOException;
6-
import java.util.Optional;
76

87
import net.lingala.zip4j.ZipFile;
98
import net.lingala.zip4j.io.outputstream.ZipOutputStream;
@@ -13,7 +12,7 @@
1312
/**
1413
* This class adds a static preview to the crate, which consists of a
1514
* metadataHtml file and a folder containing other files required to render
16-
* metadataHtml. If will be put unchanged to the writer output, i.e., a zip
15+
* metadataHtml. It will be put unchanged to the writer output, i.e., a zip
1716
* file, folder, or stream.
1817
*
1918
* @author jejkal

0 commit comments

Comments
 (0)