Skip to content

Commit 5585b5a

Browse files
damienstamatesdamienstamates
authored
Merge pull request #1 from northwesternmutual/pull_request_damien
Initial Release
2 parents 7b1a509 + 05ecefa commit 5585b5a

File tree

414 files changed

+31025
-0
lines changed

Some content is hidden

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

414 files changed

+31025
-0
lines changed

‎.gitignore

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Hidden
2+
.gopath~
3+
.DS_Store
4+
.vscode
5+
6+
# Directories
7+
vendor
8+
bin
9+
n1data
10+
n2data
11+
n3data
12+
portainer-data
13+
scripts/db
14+
scripts/log

‎.travis.yml

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
sudo: false
2+
3+
language: go
4+
5+
env:
6+
- GO111MODULE=on
7+
8+
go:
9+
- 1.11.x
10+
11+
git:
12+
depth: 1
13+
14+
before_script:
15+
- go mod vendor
16+
17+
script:
18+
- go test -v -parallel 3 --race ./...

‎CONTRIBUTING.md

+109
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# How to Contribute to Grammes
2+
3+
## Getting Started
4+
5+
This project uses Go modules to manage dependencies, and is built on Go version `1.11`.
6+
7+
```sh
8+
==> go get github.com/northwesternmutual/grammes
9+
```
10+
11+
## Testing
12+
13+
Grammes unit tests can be run by directing yourself to the root directory for the project and running this command in a terminal:
14+
15+
```sh
16+
==> go test -parallel 3 --race ./...
17+
```
18+
19+
## Project Structure
20+
21+
Below is an overview of this project's structure (files are not listed)
22+
23+
```flat
24+
github.com/northwesternmutual/grammes
25+
assets/ - Contains images and shell scripts for customizing JanusGraph
26+
docs/ - Miscellaneous documents and charts to help explain Grammes
27+
examples/ - Examples of all resources on how to use Grammes
28+
gremconnect/ - The package for handling connections and dialers
29+
gremerror/ - Contains custom error types for Grammes
30+
logging/ - Has the custom loggers for the Grammes client
31+
manager/ - Contains the GraphManager and all graph related functions
32+
model/ - Holds all of the structs and methods for Go counterpart objects
33+
query/ - Contains query related packages and the Query interface
34+
cardinality/ - Describes the number of relationship occurrences
35+
column/ - Used to reference particular parts of a column in Gremlin
36+
consumer/ - Controls how barriers emit their values
37+
datatype/ - String counterparts to reference Gremlin types
38+
direction/ - Denotes the direction of edges
39+
graph/ - The verbose graph traversal object (Query)
40+
multiplicity/ - Controls property sets for edges
41+
operator/ - Used to apply mathematical operations in a graph traversal
42+
pop/ - Determines the gathered values
43+
predicate/ - Controls the search conditions of a query
44+
scope/ - Controls the relations of a graph traversal
45+
token/ - Defines the parts of a vertex
46+
traversal/ - The preferred graph traversal (Query)
47+
quick/ - Used when executing queries without a Grammes client
48+
testing/ - Has the mock for the GraphManager when testing Grammes in your project
49+
```
50+
51+
## Imports Grouping
52+
53+
This projects adheres to the following pattern when grouping imports in Go files:
54+
55+
* imports from standard library
56+
* imports from other projects
57+
* imports from internal project
58+
59+
In addition, imports in each group must be sorted by length. For example:
60+
61+
```go
62+
import (
63+
"time"
64+
"errors"
65+
66+
"go.uber.org/zap"
67+
68+
"github.com/northwesternmutual/grammes/query/token"
69+
"github.com/northwesternmutual/grammes"
70+
)
71+
```
72+
73+
## Making a Change
74+
75+
Before making any significant changes, please [open an issue](https://github.com/northwesternmutual/grammes/issues). Discussing your proposed changes ahead of time will make the contribution process smooth for everyone.
76+
77+
Once we've discussed your changes and you've got your code ready, make sure that tests are passing (go test) and open your PR. Your pull request is most likely to be accepted if it:
78+
79+
* Includes tests for new functionality.
80+
* Follows the guidelines in [Effective Go](https://golang.org/doc/effective_go.html) and the [Go team's common code review comments](https://github.com/golang/go/wiki/CodeReviewComments).
81+
* Has a good commit message.
82+
83+
## License
84+
85+
By contributing your code, you agree to license your contribution under the terms of the [Apache License](https://github.com/northwesternmutual/grammes/blob/master/LICENSE).
86+
87+
If you are adding a new file it should have a header like below.
88+
89+
```flat
90+
// Copyright (c) 2018 Northwestern Mutual.
91+
//
92+
// Permission is hereby granted, free of charge, to any person obtaining a copy
93+
// of this software and associated documentation files (the "Software"), to deal
94+
// in the Software without restriction, including without limitation the rights
95+
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
96+
// copies of the Software, and to permit persons to whom the Software is
97+
// furnished to do so, subject to the following conditions:
98+
//
99+
// The above copyright notice and this permission notice shall be included in
100+
// all copies or substantial portions of the Software.
101+
//
102+
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
103+
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
104+
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
105+
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
106+
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
107+
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
108+
// THE SOFTWARE.
109+
```

‎README.md

+228
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
<p align="center">
2+
<img src="assets/img/grammes-gopher-v4.png" alt="Grammes" title="Grammes" width="50%">
3+
</p>
4+
5+
# Grammes
6+
7+
[![Build Status](https://travis-ci.com/northwesternmutual/grammes.svg?branch=master)](https://travis-ci.com/northwesternmutual/grammes) [![Coverage Status](https://coveralls.io/repos/github/northwesternmutual/grammes/badge.svg?branch=master)](https://coveralls.io/github/northwesternmutual/grammes?branch=master) [![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://godoc.org/github.com/northwesternmutual/grammes) [![Go Report Card](https://goreportcard.com/badge/github.com/northwesternmutual/grammes)](https://goreportcard.com/report/github.com/northwesternmutual/grammes)
8+
9+
Grammes is an API/Wrapper for Gremlin and Janusgraph. It's written purely in Golang and allows for easy use of Gremlin without touching the Gremlin terminal.
10+
11+
## Table of Contents
12+
13+
- [Grammes](#grammes)
14+
- [Table of Contents](#table-of-contents)
15+
- [Local Setup](#local-setup)
16+
- [Cloning Grammes](#cloning-grammes)
17+
- [Setting up JanusGraph](#setting-up-janusgraph)
18+
- [Using Grammes](#using-grammes)
19+
- [Testing Grammes](#testing-grammes)
20+
- [Additional Resources](#additional-resources)
21+
- [Documentation on Gremlin](#documentation-on-gremlin)
22+
- [Examples](#examples)
23+
- [Troubleshooting](#troubleshooting)
24+
- [Fixing time outs when starting Janusgraph](#fixing-time-outs-when-starting-janusgraph)
25+
26+
## Local Setup
27+
28+
You need to setup all of the following tools to run the service locally
29+
30+
- Go 1.12
31+
- Git
32+
- Elastic Search
33+
- Cassandra
34+
- Java 8
35+
36+
---
37+
38+
### Cloning Grammes
39+
40+
Begin by opening up a terminal or command prompt and clone the grammes repository.
41+
42+
```sh
43+
go get -u github.com/northwesternmutual/grammes
44+
```
45+
46+
---
47+
48+
### Setting up JanusGraph
49+
50+
*if you have decided to use another graph database then you may move on to [project setup](#using-grammes)*
51+
52+
First off, direct your terminal to the Grammes' `scripts` directory.
53+
54+
```sh
55+
cd $GOPATH/src/github.com/northwesternmutual/grammes/scripts
56+
```
57+
58+
In here you can find the `gremlin.sh` and `janusgraph.sh` scripts. To set up JanusGraph just run the `janusgraph.sh` script.
59+
60+
```sh
61+
./janusgraph.sh
62+
```
63+
64+
This should download and/or begin the graph and TinkerPop server.
65+
66+
To make sure that everything is running try running `gremlin.sh`.
67+
68+
```sh
69+
$ ./gremlin.sh
70+
SLF4J: Class path contains multiple SLF4J bindings.
71+
SLF4J: Found binding in [jar:file:/Users/<username>/projects/nm/gocode/src/github.com/northwesternmutual/grammes/bin/janusgraph-0.3.1-hadoop2/lib/slf4j-log4j12-1.7.12.jar!/org/slf4j/impl/StaticLoggerBinder.class]
72+
SLF4J: Found binding in [jar:file:/Users/<username>/projects/nm/gocode/src/github.com/northwesternmutual/grammes/bin/janusgraph-0.3.1-hadoop2/lib/logback-classic-1.1.2.jar!/org/slf4j/impl/StaticLoggerBinder.class]
73+
SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an explanation.
74+
SLF4J: Actual binding is of type [org.slf4j.impl.Log4jLoggerFactory]
75+
15:05:59 WARN org.apache.hadoop.util.NativeCodeLoader - Unable to load native-hadoop library for your platform... using builtin-java classes where applicable
76+
gremlin>
77+
```
78+
79+
Once Gremlin starts then you may begin by running this command.
80+
81+
```sh
82+
gremlin> :remote connect tinkerpop.server conf/remote.yaml
83+
===>Configured localhost/127.0.0.1:8182
84+
```
85+
86+
If you see the message that Gremlin was configured to the localhost then quit Gremlin.
87+
88+
```sh
89+
gremlin> :exit
90+
```
91+
92+
Finally, run the `janusgraph.sh` script again, but this time with the `status` flag.
93+
94+
```sh
95+
./janusgraph.sh status
96+
```
97+
98+
---
99+
100+
### Using Grammes
101+
102+
Once you have cloned the repository then you may begin implementing it into a project. Let's begin with creating a place for your code in the `$GOPATH`, i.e.,
103+
104+
```sh
105+
$GOPATH/src/github.com/<username-here>/<project-name-here>
106+
```
107+
108+
Next, you'll want to create a `main.go` file. For this example I will be using [MS Code](https://code.visualstudio.com/download), but you may use any editor you prefer.
109+
110+
```sh
111+
code main.go
112+
```
113+
114+
In this file we can begin by making it a typical empty `main.go` file like this:
115+
116+
``` go
117+
package main
118+
119+
func main() {
120+
}
121+
```
122+
123+
Next, import the grammes package and begin using it by connecting your client to a gremlin server.
124+
125+
``` go
126+
package main
127+
128+
import (
129+
"log"
130+
131+
"github.com/northwesternmutual/grammes"
132+
)
133+
134+
func main() {
135+
// Creates a new client with the localhost IP.
136+
client, err := grammes.DialWithWebSocket("ws://127.0.0.1:8182")
137+
if err != nil {
138+
log.Fatalf("Error while creating client: %s\n", err.Error())
139+
}
140+
141+
// Executing a basic query to assure that the client is working.
142+
res, err := client.ExecuteStringQuery("1+3")
143+
if err != nil {
144+
log.Fatalf("Querying error: %s\n", err.Error())
145+
}
146+
147+
// Print out the result as a string
148+
log.Println(string(res))
149+
}
150+
```
151+
152+
Once the client is created then you can begin querying the gremlin server via the `.ExecuteQuery` method in the client. To use this function you must put in a `Query` which is an interface for any kind of Query-able type in the package. These include: `graph.String` and `traversal.String`. For an example of querying the gremlin server for all of the Vertex labels:
153+
154+
``` go
155+
package main
156+
157+
import (
158+
"log"
159+
160+
"github.com/northwesternmutual/grammes"
161+
)
162+
163+
func main() {
164+
// Creates a new client with the localhost IP.
165+
client, err := grammes.DialWithWebSocket("ws://127.0.0.1:8182")
166+
if err != nil {
167+
log.Fatalf("Error while creating client: %s\n", err.Error())
168+
}
169+
170+
// Executing a query to add a vertex to the graph.
171+
client.AddVertex("testingvertex")
172+
173+
// Create a new traversal string to build your traverser.
174+
g := grammes.Traversal()
175+
176+
// Executing a query to fetch all of the labels from the vertices.
177+
data, err := client.ExecuteQuery(g.V().Label())
178+
if err != nil {
179+
log.Fatalf("Querying error: %s\n", err.Error())
180+
}
181+
182+
// Log out the response.
183+
log.Println(string(data))
184+
}
185+
```
186+
187+
After this is all written you may run this file by saving it and hopping back on to your terminal. After starting your Gremlin Server and graph database in the terminal let's run this command to run the file:
188+
189+
```sh
190+
go run main.go
191+
```
192+
193+
For more examples look in the `examples/` directory of the project. In there you'll find multiple examples on how to use the Grammes package.
194+
195+
## Testing Grammes
196+
197+
Grammes uses [goconvey](https://www.github.com/smartystreets/goconvey/) by [smartystreets](https://www.github.com/smartystreets/) for its tests. Before trying to run the unit tests in Grammes you should update your version of this repository using this command.
198+
199+
```sh
200+
go get -u github.com/smartystreets/goconvey/convey
201+
```
202+
203+
Once you have this downloaded you may run the tests in Grammes how you normally would in Golang.
204+
205+
```sh
206+
go test ./...
207+
```
208+
209+
## Additional Resources
210+
211+
### Documentation on Gremlin
212+
213+
To learn more about how to use Gremlin I highly recommend looking through their [Tinkerpop3 documentation](http://tinkerpop.apache.org/docs/current/reference/). It's full of examples and documentation on every traversal step available.
214+
215+
### Examples
216+
217+
To find examples look in the `examples/` directory of Grammes. In there you'll find plenty of examples related to how to use this package. Make sure you're running Janusgraph before you begin running the examples.
218+
219+
## Troubleshooting
220+
221+
### Fixing time outs when starting Janusgraph
222+
223+
If Nodetool times out or any other part of the setup times out then the most common issue is that Cassandra is already running on your machine. To fix this run this command.
224+
225+
``` bash
226+
# only for Unix at the moment.
227+
launchctl unload ~/Library/LaunchAgents/homebrew.mxcl.cassandra.plist
228+
```

0 commit comments

Comments
 (0)