Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/elasticpath/rest-resource-viz

rest-resource visualizer
https://github.com/elasticpath/rest-resource-viz

clojure clojurescript d3

Last synced: about 1 month ago
JSON representation

rest-resource visualizer

Awesome Lists containing this project

README 

        
# rest-resources-viz



Manipulate and visualize Cortex rest resources and relationships.



![Resource Graph Showcase](doc/img/resource-graph-showcase.png)



## Usage



Rest-resources-viz extracts the graph data from Elastic Path's resource definitions (just specify the dependencies) and therefore needs access to the Maven artifacts that contain them.



In order to do this you would need to add the `com.elasticpath/rest-viz-maven-plugin` to your `pom.xml` this way:



```xml



  

    com.elasticpath

    rest-viz-maven-plugin

    X.Y.Z

    

      

        extract-viz-data

        package 

        

          extract

        

      

    

    

      

      



      

      



      

      

    



    

      

    

  



```



The above generates all the necessary web assets to the specified output directory (or `rest-viz-assets`) and can be served directly.

The sample project in the repository can help with setting up your project. If artifacts cannot be found, make also sure that the correct repository has been specified in `.m2/settings.xml` and/or the correct profile has been activated.



If you want to just extract the data, at the command line you can call the goal explicitly (check [Plugin Prefix Resolution](https://maven.apache.org/guides/introduction/introduction-to-plugin-prefix-mapping.html) to type less):



    mvn com.elasticpath:rest-viz-maven-plugin:extract

    

The only supported output at the moment is the [Extensible Data Format](https://github.com/edn-format/edn). [Here](https://github.com/bpsm/edn-java) you can find a Java reader implementation.



### Simple(r) Visualization



There is another way to visualize the resource graph. It requires cloning this repository and familiarizing yourself with the Clojure world. First of all the JavaScript app and assets needs to be materialized in `target`:



```

boot build-web target

```



The conf file passed in is necessary in order to configure the Maven repository and coordinates (assuming they have a similar name) for the resource artifacts. For a sample configuration see `conf-sample.edn` in the repository root.

In case of missing keys a `clojure.spec` error will tell you what was expected. The error message is a bit cryptic and will be improved, bear with us.



Once the command finishes, you can serve the `target` folder.



A simple way to serve a folder is by using `python2`, for instance:



```

cd target && python2 -m SimpleHTTPServer; cd..

```



Python 3 has got a slightly different command line:



```

cd target && python3 -m http.server; cd..

```



Now you can open your browser and connect to `localhost:8000`. You will see an empty frame. This is because the graph data is missing. That can be easily generated with the `extract` task (see `boot extract -h` as well) and needs to be saved in `target/graph-data.edn`:



```

boot extract --conf my-conf.edn --graph-edn target/graph-data.edn --pretty

```



Note that we are creating the file in `target` now - the app should pick up the changes (React is your friend). If not, reload the page.



## Details



The project contains three main deliverables: the extractor, the website and the plugin. The extractor is the piece of code which scans and creates the data file used by the website.  The maven plugin just wraps them in a convenient way for consumption.



For all the available tasks run `boot -h`. The tasks prefixed with `dev-` tipically start in-context repl. Every task also has its own `-h/--help` switch.



### Extractor



The extractor is a direct dependency of the plugin and needs to be installed:



    boot install-extractor



Additionally, it can read the resource xmls from Maven and dump the graph data using the `extract` task:



    boot extract -- -g data/graph-data2.edn -p



The above command dumps the graph data to `data/graph-data2.edn` with pretty print enabled. The brackets are necessary in order to send positional arguments to the task.



### Plugin



This is at the moment a three-step process. The extractor and the web assets needs to be compiled first and positioned in `web-target`:



    boot install-extractor



    boot build-web target --dir web-target



Then Maven needs to be invoked for compiling and installing the actual plugin:



    mvn -Pboot-clj clean install



The above will generate a `mvn-target` folder containing the artifact and install it `$USER/.m2/repository`.



The plugin is less interactive in its nature but a repl can still be launched with:



    boot dev-plugin



None of the Maven plugin classes will be available at the repl. Another useful trick is to repeatedly generate and install the plugin by watching the source files:



    boot -B --source-paths "." watch  ".*\.clj?"  -i "pom.xml" -e "^mvn-target" sift -i "src" -i "pom.xml" mvn -W `pwd` -A "-Pboot-clj clean install"



## Deploying to Sonatype



In order to deploy a staging/release artifact, the steps are almost the same as above:



    boot -P deploy-extractor -u ... -p ...          # Sonatype credentials here

    boot -P build-web target --dir web-target

    mvn -Pboot-clj -Psonatype-release clean deploy  # Credentials come from settings.xml



The `-P` avoids pulling in packages from you global `profile.boot`.



In order to use Maven gpg signing, add the following to `settings.xml`:



    

      default-profile

      

        true

      

      

        /usr/bin/gpg2

        true

        ...

        ...

      

    



## Test



    boot test



The simple command above would do.



## Boot



The build tool of choice for this project is [boot](http://boot-clj.com/)Boot Logo.

Boot enables us to use Clojure code directly, and therefore repl-driven development, when defining our build tasks.



## License



Copyright 2020 Elastic Path



Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at



    http://www.apache.org/licenses/LICENSE-2.0



Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.