This repository has been archived by the owner on Feb 12, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 11
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
9d88589
commit b61d44c
Showing
172 changed files
with
30,788 additions
and
8 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,136 @@ | ||
# AMF Java Programming guide | ||
|
||
Java wrapping code for the AMF library can be found in the `org.raml.amf` namespace. | ||
This package provides a Java friendly interface on top of the native Clojure code of the library. | ||
|
||
## Compiling | ||
|
||
At this moment we don't provide any artifacts in any repository to use AMF or these Java bindings, so they must be built manually with the help of Leiningen. | ||
In order to build the library, you fist need to build an 'ubejar' with AMF. To accomplish this, from the main AMF project directory run the following instruction: | ||
|
||
``` bash | ||
$ lein uberjar | ||
``` | ||
After Leiningen has finished you should have a standalone jar for AMF and all its dependencies in the `target/api-modeling-framework-0.1.2-SNAPSHOT-standalone.jar` location. Version might be different from the one at the moment of writing this documentation. | ||
|
||
Once the jar for AMF has been generated, we can generate the Java bindings jar. For that change to the `java` directory in the AMF project and use maven: | ||
|
||
``` bash | ||
mvn package | ||
``` | ||
|
||
After Maven has finished you should have an additional jar in the `target/amf-java-0.1.2-SNAPSHOT.jar` location with the Java bindings. Add both jars into your project to use the AMF Java bindings. | ||
|
||
## Parsing | ||
|
||
Parser can be found in the `org.raml.amf.parsers` package of the project. They can be build using the factories in `org.raml.amf.AMF` | ||
|
||
``` java | ||
DocumentModel model = AMF.RAMLParser().parseFile(new URL("http://test.com/worldmusic/api.raml")); | ||
``` | ||
|
||
Parsers are include for RAML, OpenAPI and the JSON-LD serialisation of the AMF model. | ||
|
||
Parsers can accept options, including a hash-map of URLs to local directories that will be used to resolve references in the parsed documents. | ||
|
||
For instance, in the next snippet all remote references to the URLs prefixed by `http://test.com/worldmusic` will be resolved looking into the local directory `/Users/antoniogarrote/world-music-api`. | ||
|
||
``` java | ||
HashMap<String,String> cacheDirs = new HashMap<>(); | ||
cacheDirs.put("http://test.com/worldmusic","/Users/antoniogarrote/vocabs/world-music-api"); | ||
ParsingOptions options = new ParsingOptions().setCacheDirs(cacheDirs); | ||
|
||
DocumentDocument model = (Document) AMF.RAMLParser().parseFile(new URL("http://test.com/worldmusic/api.raml"), options); | ||
``` | ||
The original parsed text can be retrieved using the `rawText` method. | ||
|
||
## Navigating the Document Model | ||
Parsing will return an instance of a subclass of `DocumentModel` Depending on what is the parsed file, a `Document` a `Fragment` or a `Module` instance will be returned. | ||
|
||
No matter what is the actual Document Model class, the returned model will also include references to all linked references in the model. | ||
|
||
These references can be listed using the `references` method and new instances of `DocumentModel` can be build for these references using the `modelForReference` method: | ||
|
||
``` java | ||
for (URL ref : model.references()) { | ||
DocumentModel refModel = model.modelForReference(ref); | ||
System.out.println("Found a reference model: " + refModel); | ||
} | ||
``` | ||
|
||
## Applying resolution | ||
|
||
To run the resolution algorithm and combine all the documents from the Document Model into a single Domain Model description, the method `resolve` can be invoked. | ||
|
||
``` java | ||
DocumentModel resolvedModel = model.resolve(); | ||
``` | ||
|
||
## Accessing the Domain Model | ||
|
||
The parsed Domain Model can be retrieved from the Document Model instance using the appropriate accessor. | ||
|
||
Fragments returns the encoded Domain Model element using the `encodes` method from the `org.raml.amf.core.document.EncodesDomainModel` interface. | ||
Modules returns the list of declared Domain Model elements using the `declares` method from the `org.raml.amf.core.document.DeclaresDomainModel` interface. | ||
Documents can use both methods to retrieve the top level encoded element and the list of declared elements in the root element. | ||
|
||
``` java | ||
if (model instanceof EncodesDomainModel) { | ||
System.out.println(model.encodes()); | ||
} | ||
|
||
if (targetModel instanceof DeclaresDomainModel) { | ||
List<DomainModel> declarations = model.declares(); | ||
for(DomainModel decl : declarations) { | ||
System.out.println(decl); | ||
} | ||
} | ||
``` | ||
|
||
## Navigating and mutating the Domain Model | ||
|
||
The Domain Model includes Java Bean classes for all elements in the AMF Domain Model. | ||
This getters and setters can be used to navigate and mutate the model. Please, refer to the [documentation](./java/apidocs/index.html) for more details. | ||
|
||
``` java | ||
APIDocumentation api = (APIDocumentation) model.encodes(); | ||
|
||
for (EndPoint endpoint : api.getEndpoints()) { | ||
endpoint.setName("Modified " + endpoint.getName()); | ||
} | ||
``` | ||
|
||
## Generating | ||
|
||
AMF includes generators capable of serialising the AMF model back into one of the supported syntaxes. The method `generateString` can be used to generate a String representation and the method `generateFile` can be used to dump the serialised model directly into a file. | ||
Factory methods for each generator can be found in the `org.raml.amf.AMF` class. | ||
|
||
|
||
``` java | ||
// Generating RAML | ||
// Generate can accept just the model | ||
String generated = AMF.RAMLGenerator().generateString(targetModel); | ||
System.out.println(generated); | ||
|
||
// Generating OpenAPI | ||
// It can also accept a destination File/URL for the model | ||
generated = AMF.OpenAPIGenerator().generateString( | ||
new File("world_music.json"), | ||
targetModel | ||
); | ||
System.out.println(generated); | ||
|
||
// Generating JSON-LD | ||
// Finally it can also accept a set of generation options | ||
generated = AMF.JSONLDGenerator().generateString( | ||
new File("world_music.jsonld"), | ||
targetModel, | ||
new GenerationOptions() | ||
.setFullgraph(true) | ||
.setSourceMapGeneration(true)); | ||
System.out.println(generated); | ||
``` | ||
|
||
Two options are available when generating JSON-LD documents. | ||
`setFullGraph` will nest the JSON-LD graphs for the referenced documents in the model to be serialised, otherwise only URIs will be generated. | ||
`setSourceMapGeneration` enables or disables the generation of source maps JSON-LD information in the output. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,58 @@ | ||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> | ||
<!-- NewPage --> | ||
<html lang="en"> | ||
<head> | ||
<!-- Generated by javadoc (1.8.0_92) on Thu May 04 21:46:11 BST 2017 --> | ||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> | ||
<title>All Classes (api-modeling-framework java bindings 0.1.2-SNAPSHOT API)</title> | ||
<meta name="date" content="2017-05-04"> | ||
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style"> | ||
<script type="text/javascript" src="script.js"></script> | ||
</head> | ||
<body> | ||
<h1 class="bar">All Classes</h1> | ||
<div class="indexContainer"> | ||
<ul> | ||
<li><a href="org/raml/amf/AMF.html" title="class in org.raml.amf" target="classFrame">AMF</a></li> | ||
<li><a href="org/raml/amf/generators/AMFJSONLDGenerator.html" title="class in org.raml.amf.generators" target="classFrame">AMFJSONLDGenerator</a></li> | ||
<li><a href="org/raml/amf/parsers/AMFJSONLDParser.html" title="class in org.raml.amf.parsers" target="classFrame">AMFJSONLDParser</a></li> | ||
<li><a href="org/raml/amf/core/domain/APIDocumentation.html" title="class in org.raml.amf.core.domain" target="classFrame">APIDocumentation</a></li> | ||
<li><a href="org/raml/amf/generators/BaseGenerator.html" title="class in org.raml.amf.generators" target="classFrame">BaseGenerator</a></li> | ||
<li><a href="org/raml/amf/parsers/BaseParser.html" title="class in org.raml.amf.parsers" target="classFrame">BaseParser</a></li> | ||
<li><a href="org/raml/amf/examples/BasicParsingAndNavigation.html" title="class in org.raml.amf.examples" target="classFrame">BasicParsingAndNavigation</a></li> | ||
<li><a href="org/raml/amf/utils/Clojure.html" title="class in org.raml.amf.utils" target="classFrame">Clojure</a></li> | ||
<li><a href="org/raml/amf/core/document/DeclaresDomainModel.html" title="interface in org.raml.amf.core.document" target="classFrame"><span class="interfaceName">DeclaresDomainModel</span></a></li> | ||
<li><a href="org/raml/amf/core/document/Document.html" title="class in org.raml.amf.core.document" target="classFrame">Document</a></li> | ||
<li><a href="org/raml/amf/core/document/DocumentModel.html" title="class in org.raml.amf.core.document" target="classFrame">DocumentModel</a></li> | ||
<li><a href="org/raml/amf/core/domain/DomainModel.html" title="class in org.raml.amf.core.domain" target="classFrame">DomainModel</a></li> | ||
<li><a href="org/raml/amf/core/document/EncodesDomainModel.html" title="interface in org.raml.amf.core.document" target="classFrame"><span class="interfaceName">EncodesDomainModel</span></a></li> | ||
<li><a href="org/raml/amf/core/domain/EndPoint.html" title="class in org.raml.amf.core.domain" target="classFrame">EndPoint</a></li> | ||
<li><a href="org/raml/amf/core/document/Fragment.html" title="class in org.raml.amf.core.document" target="classFrame">Fragment</a></li> | ||
<li><a href="org/raml/amf/generators/GenerationException.html" title="class in org.raml.amf.generators" target="classFrame">GenerationException</a></li> | ||
<li><a href="org/raml/amf/generators/GenerationOptions.html" title="class in org.raml.amf.generators" target="classFrame">GenerationOptions</a></li> | ||
<li><a href="org/raml/amf/core/domain/GenericOperationUnit.html" title="class in org.raml.amf.core.domain" target="classFrame">GenericOperationUnit</a></li> | ||
<li><a href="org/raml/amf/core/domain/GenericParameter.html" title="class in org.raml.amf.core.domain" target="classFrame">GenericParameter</a></li> | ||
<li><a href="org/raml/amf/core/domain/GenericTag.html" title="class in org.raml.amf.core.domain" target="classFrame">GenericTag</a></li> | ||
<li><a href="org/raml/amf/core/domain/Header.html" title="class in org.raml.amf.core.domain" target="classFrame">Header</a></li> | ||
<li><a href="org/raml/amf/core/exceptions/InvalidModelException.html" title="class in org.raml.amf.core.exceptions" target="classFrame">InvalidModelException</a></li> | ||
<li><a href="org/raml/amf/core/Model.html" title="class in org.raml.amf.core" target="classFrame">Model</a></li> | ||
<li><a href="org/raml/amf/core/document/Module.html" title="class in org.raml.amf.core.document" target="classFrame">Module</a></li> | ||
<li><a href="org/raml/amf/generators/OpenAPIGenerator.html" title="class in org.raml.amf.generators" target="classFrame">OpenAPIGenerator</a></li> | ||
<li><a href="org/raml/amf/parsers/OpenAPIParser.html" title="class in org.raml.amf.parsers" target="classFrame">OpenAPIParser</a></li> | ||
<li><a href="org/raml/amf/core/domain/Operation.html" title="class in org.raml.amf.core.domain" target="classFrame">Operation</a></li> | ||
<li><a href="org/raml/amf/core/domain/Parameter.html" title="class in org.raml.amf.core.domain" target="classFrame">Parameter</a></li> | ||
<li><a href="org/raml/amf/parsers/ParsingException.html" title="class in org.raml.amf.parsers" target="classFrame">ParsingException</a></li> | ||
<li><a href="org/raml/amf/parsers/ParsingOptions.html" title="class in org.raml.amf.parsers" target="classFrame">ParsingOptions</a></li> | ||
<li><a href="org/raml/amf/core/domain/Payload.html" title="class in org.raml.amf.core.domain" target="classFrame">Payload</a></li> | ||
<li><a href="org/raml/amf/generators/RAMLGenerator.html" title="class in org.raml.amf.generators" target="classFrame">RAMLGenerator</a></li> | ||
<li><a href="org/raml/amf/parsers/RAMLParser.html" title="class in org.raml.amf.parsers" target="classFrame">RAMLParser</a></li> | ||
<li><a href="org/raml/amf/core/domain/Request.html" title="class in org.raml.amf.core.domain" target="classFrame">Request</a></li> | ||
<li><a href="org/raml/amf/core/exceptions/ResolutionException.html" title="class in org.raml.amf.core.exceptions" target="classFrame">ResolutionException</a></li> | ||
<li><a href="org/raml/amf/core/domain/Response.html" title="class in org.raml.amf.core.domain" target="classFrame">Response</a></li> | ||
<li><a href="org/raml/amf/core/domain/SourceMap.html" title="class in org.raml.amf.core.domain" target="classFrame">SourceMap</a></li> | ||
<li><a href="org/raml/amf/core/domain/Type.html" title="class in org.raml.amf.core.domain" target="classFrame">Type</a></li> | ||
<li><a href="org/raml/amf/core/exceptions/UnknownModelReferenceException.html" title="class in org.raml.amf.core.exceptions" target="classFrame">UnknownModelReferenceException</a></li> | ||
</ul> | ||
</div> | ||
</body> | ||
</html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,58 @@ | ||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> | ||
<!-- NewPage --> | ||
<html lang="en"> | ||
<head> | ||
<!-- Generated by javadoc (1.8.0_92) on Thu May 04 21:46:11 BST 2017 --> | ||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> | ||
<title>All Classes (api-modeling-framework java bindings 0.1.2-SNAPSHOT API)</title> | ||
<meta name="date" content="2017-05-04"> | ||
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style"> | ||
<script type="text/javascript" src="script.js"></script> | ||
</head> | ||
<body> | ||
<h1 class="bar">All Classes</h1> | ||
<div class="indexContainer"> | ||
<ul> | ||
<li><a href="org/raml/amf/AMF.html" title="class in org.raml.amf">AMF</a></li> | ||
<li><a href="org/raml/amf/generators/AMFJSONLDGenerator.html" title="class in org.raml.amf.generators">AMFJSONLDGenerator</a></li> | ||
<li><a href="org/raml/amf/parsers/AMFJSONLDParser.html" title="class in org.raml.amf.parsers">AMFJSONLDParser</a></li> | ||
<li><a href="org/raml/amf/core/domain/APIDocumentation.html" title="class in org.raml.amf.core.domain">APIDocumentation</a></li> | ||
<li><a href="org/raml/amf/generators/BaseGenerator.html" title="class in org.raml.amf.generators">BaseGenerator</a></li> | ||
<li><a href="org/raml/amf/parsers/BaseParser.html" title="class in org.raml.amf.parsers">BaseParser</a></li> | ||
<li><a href="org/raml/amf/examples/BasicParsingAndNavigation.html" title="class in org.raml.amf.examples">BasicParsingAndNavigation</a></li> | ||
<li><a href="org/raml/amf/utils/Clojure.html" title="class in org.raml.amf.utils">Clojure</a></li> | ||
<li><a href="org/raml/amf/core/document/DeclaresDomainModel.html" title="interface in org.raml.amf.core.document"><span class="interfaceName">DeclaresDomainModel</span></a></li> | ||
<li><a href="org/raml/amf/core/document/Document.html" title="class in org.raml.amf.core.document">Document</a></li> | ||
<li><a href="org/raml/amf/core/document/DocumentModel.html" title="class in org.raml.amf.core.document">DocumentModel</a></li> | ||
<li><a href="org/raml/amf/core/domain/DomainModel.html" title="class in org.raml.amf.core.domain">DomainModel</a></li> | ||
<li><a href="org/raml/amf/core/document/EncodesDomainModel.html" title="interface in org.raml.amf.core.document"><span class="interfaceName">EncodesDomainModel</span></a></li> | ||
<li><a href="org/raml/amf/core/domain/EndPoint.html" title="class in org.raml.amf.core.domain">EndPoint</a></li> | ||
<li><a href="org/raml/amf/core/document/Fragment.html" title="class in org.raml.amf.core.document">Fragment</a></li> | ||
<li><a href="org/raml/amf/generators/GenerationException.html" title="class in org.raml.amf.generators">GenerationException</a></li> | ||
<li><a href="org/raml/amf/generators/GenerationOptions.html" title="class in org.raml.amf.generators">GenerationOptions</a></li> | ||
<li><a href="org/raml/amf/core/domain/GenericOperationUnit.html" title="class in org.raml.amf.core.domain">GenericOperationUnit</a></li> | ||
<li><a href="org/raml/amf/core/domain/GenericParameter.html" title="class in org.raml.amf.core.domain">GenericParameter</a></li> | ||
<li><a href="org/raml/amf/core/domain/GenericTag.html" title="class in org.raml.amf.core.domain">GenericTag</a></li> | ||
<li><a href="org/raml/amf/core/domain/Header.html" title="class in org.raml.amf.core.domain">Header</a></li> | ||
<li><a href="org/raml/amf/core/exceptions/InvalidModelException.html" title="class in org.raml.amf.core.exceptions">InvalidModelException</a></li> | ||
<li><a href="org/raml/amf/core/Model.html" title="class in org.raml.amf.core">Model</a></li> | ||
<li><a href="org/raml/amf/core/document/Module.html" title="class in org.raml.amf.core.document">Module</a></li> | ||
<li><a href="org/raml/amf/generators/OpenAPIGenerator.html" title="class in org.raml.amf.generators">OpenAPIGenerator</a></li> | ||
<li><a href="org/raml/amf/parsers/OpenAPIParser.html" title="class in org.raml.amf.parsers">OpenAPIParser</a></li> | ||
<li><a href="org/raml/amf/core/domain/Operation.html" title="class in org.raml.amf.core.domain">Operation</a></li> | ||
<li><a href="org/raml/amf/core/domain/Parameter.html" title="class in org.raml.amf.core.domain">Parameter</a></li> | ||
<li><a href="org/raml/amf/parsers/ParsingException.html" title="class in org.raml.amf.parsers">ParsingException</a></li> | ||
<li><a href="org/raml/amf/parsers/ParsingOptions.html" title="class in org.raml.amf.parsers">ParsingOptions</a></li> | ||
<li><a href="org/raml/amf/core/domain/Payload.html" title="class in org.raml.amf.core.domain">Payload</a></li> | ||
<li><a href="org/raml/amf/generators/RAMLGenerator.html" title="class in org.raml.amf.generators">RAMLGenerator</a></li> | ||
<li><a href="org/raml/amf/parsers/RAMLParser.html" title="class in org.raml.amf.parsers">RAMLParser</a></li> | ||
<li><a href="org/raml/amf/core/domain/Request.html" title="class in org.raml.amf.core.domain">Request</a></li> | ||
<li><a href="org/raml/amf/core/exceptions/ResolutionException.html" title="class in org.raml.amf.core.exceptions">ResolutionException</a></li> | ||
<li><a href="org/raml/amf/core/domain/Response.html" title="class in org.raml.amf.core.domain">Response</a></li> | ||
<li><a href="org/raml/amf/core/domain/SourceMap.html" title="class in org.raml.amf.core.domain">SourceMap</a></li> | ||
<li><a href="org/raml/amf/core/domain/Type.html" title="class in org.raml.amf.core.domain">Type</a></li> | ||
<li><a href="org/raml/amf/core/exceptions/UnknownModelReferenceException.html" title="class in org.raml.amf.core.exceptions">UnknownModelReferenceException</a></li> | ||
</ul> | ||
</div> | ||
</body> | ||
</html> |
Oops, something went wrong.