Skip to content

Commit

Permalink
Move usage doc from README to wiki
Browse files Browse the repository at this point in the history
  • Loading branch information
@liry
liry committed Jun 17, 2015
1 parent a5ab759 commit 39af689
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 187 deletions.
27 changes: 18 additions & 9 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@ Below are few **rules, recommendations and best practices** we try to follow whe
* Every pull request with non-trivial change must be **associated with an issue**.
* Every closed non-rejected pull request and issue must be marked with exactly **one milestone version**.
* Issue must be **properly labeled** (bug/enhancement/backward incompatible/...).
* Add usage examples of new high level functionality to [README.md](README.md)
* Add usage examples of new high level functionality to
[documentation](https://github.com/martiner/gooddata-java/wiki/Code-Examples).

## Design

Expand All @@ -15,37 +16,45 @@ Below are few **rules, recommendations and best practices** we try to follow whe
* Don't create single implementation interfaces for services.

### DTOs
* All DTOs which can be updated should be **mutable**. Please keep mutable only the fields which are subject of change, the rest should be immutable.
* All DTOs which can be updated should be **mutable**. Please keep mutable only the fields which are subject of change,
the rest should be immutable.
* Create method named `String getUri()` to provide **link to self**.
* Introduce **constants**:
```java
public static final String URI = "/gdc/someresource/{resource-id}";
public static final UriTemplate TEMPLATE = new UriTemplate(URI);
```
* Put _Jackson_ annotations on getters rather then on fields.
* Consider the **visibility** - use `package protected` when DTO is not intended for SDK user, but is needed in related service.
* Consider the **visibility** - use `package protected` when DTO is not intended for SDK user, but is needed
in related service.
* Test all DTOs using _[JsonUnit](https://github.com/lukas-krecan/JsonUnit)_.

### Enums
* Use enums sparingly, because they don't work with REST API changes (eg. new value added on the backend) **never use them when deserializing**.
* Use enums sparingly, because they don't work with REST API changes (eg. new value added on the backend) **never use
them when deserializing**.
* Where make sense, use overloaded methods with an enum argument as well as `String` argument.

### Services
* When programming client for some polling return [`FutureResult`](src/main/java/com/gooddata/FutureResult.java) to enable user asynchronous call.
* Create custom [`GoodDataException`](src/main/java/com/gooddata/GoodDataException.java) when you feel the case is specific enough.
* When programming client for some polling return [`FutureResult`](src/main/java/com/gooddata/FutureResult.java)
to enable user asynchronous call.
* Create custom [`GoodDataException`](src/main/java/com/gooddata/GoodDataException.java) when you feel the case
is specific enough.
* Prefer DTOs to `String` or primitive arguments.
* **Method naming**:
* `get*()` when searching form single object (throw exception when no or multiple objects are found, never return `null`)
* `get*()` when searching form single object (throw exception when no or multiple objects are found,
never return `null`)
* `find*()` when searching for multiple objects (collection of objects, never return `null`)
* `remove*()` (i.e. `remove(Project project)`) instead od `delete*()`
* Write **integration tests** for services using _[Jadler](https://github.com/jadler-mocking/jadler/wiki)_.
* If it is possible write **acceptance tests** to be run with the real backend.
* Update [`README`](README.md) with usage examples.
* Update [documentation](https://github.com/martiner/gooddata-java/wiki/Code-Examples) with usage examples.

## Best practices
* **Test class naming**:
* `*Test` unit tests
* `*IT` integration tests (see [`AbstractGoodDataIT`](src/test/java/com/gooddata/AbstractGoodDataIT.java))
* `*AT` acceptance tests
* Everything public should be **documented** using _javadoc_.
* When you need some **utility code**, look for handy utilities in used libraries first (e.g. _Spring_ has its `StreamUtils`, `FileCopyUtils`, ...). When you decide to create new utility class, use _abstract utility class pattern_.
* When you need some **utility code**, look for handy utilities in used libraries first (e.g. _Spring_ has
its `StreamUtils`, `FileCopyUtils`, ...). When you decide to create new utility class,
use _abstract utility class pattern_.
186 changes: 8 additions & 178 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
# GoodData Java SDK

[![Build Status](https://travis-ci.org/martiner/gooddata-java.png?branch=master)](https://travis-ci.org/martiner/gooddata-java)
# GoodData Java SDK [![Build Status](https://travis-ci.org/martiner/gooddata-java.png?branch=master)](https://travis-ci.org/martiner/gooddata-java)

The *GoodData Java SDK* encapsulates the REST API provided by the [GoodData](http://www.gooddata.com) platform.
The first version was implemented during the [All Data Hackathon](http://hackathon.gooddata.com) April 10 - 11 2014
and currently the SDK is transitioned to be an official GoodData project.

## Usage

See [Wiki](https://github.com/martiner/gooddata-java/wiki) for [Code Examples](https://github.com/martiner/gooddata-java/wiki/Code-Examples)
and [Extensibility How-To](https://github.com/martiner/gooddata-java/wiki/Extending-GoodData-Java-SDK).

The *GoodData Java SDK* is available in Maven Central Repository, to use it from Maven add to `pom.xml`:

```xml
Expand All @@ -28,180 +29,9 @@ The *GoodData Java SDK* uses:
* the *Spring Framework* (version 3.x)
* the *Jackson JSON Processor* (version 1.9)

### General

```java
GoodData gd = new GoodData("roman@gooddata.com", "Roman1");
gd.logout();
```

### Project API

List projects, create a project,...
```java
ProjectService projectService = gd.getProjectService();
Collection<Project> projects = projectService.getProjects();
Project project = projectService.createProject(new Project("my project", "MyToken")).get();
```

Validate project
```java
Set<ProjectValidationType> types = projectService.getAvailableProjectValidationTypes(project);
ProjectValidationResults results = projectService.validateProject(project, types).get();
```

List project users
```java
ProjectService projectService = gd.getProjectService();
List<User> users = new ArrayList<>();
List<User> page;
while (!(page = projectService.listUsers(project, new PageRequest(users.size(), 100))).isEmpty()) {
users.addAll(page);
}
```

List project user roles
```java
ProjectService projectService = gd.getProjectService();
Set<Role> roles = projectService.getRoles(project);
```

### Project Model API

Create and update the project model, execute MAQL DDL,...

```java
ModelService modelService = gd.getModelService();
ModelDiff diff = modelService.getProjectModelDiff(project,
new InputStreamReader(getClass().getResourceAsStream("/person.json"))).get();
modelService.updateProjectModel(project, diff).get();

modelService.updateProjectModel(project, "MAQL DDL EXPRESSION").get();
```

### Metadata API

Query, create, update and remove project metadata - attributes, facts, metrics, reports,...

```java
MetadataService md = gd.getMetadataService();

String fact = md.getObjUri(project, Fact.class, identifier("fact.person.shoesize"));
Metric m = md.createObj(project, new Metric("Avg shoe size", "SELECT AVG([" + fact + "])", "#,##0"));

Attribute attr = md.getObj(project, Attribute.class, identifier("attr.person.department"));

ReportDefinition definition = GridReportDefinitionContent.create(
"Department avg shoe size",
asList("metricGroup"),
asList(new AttributeInGrid(attr.getDefaultDisplayForm().getUri())),
asList(new GridElement(m.getUri(), "Avg shoe size"))
);
definition = md.createObj(project, definition);
Report report = md.createObj(project, new Report(definition.getTitle(), definition));

md.removeObj(report)
```

Create and retrieve scheduled mails on reports and dashboards:

```java
Project project = ...
ReportDefinition reportDefinition = ...

MetadataService md = gd.getMetadataService();
ScheduledMail scheduledMail = md.createObj(
project,
(new ScheduledMail("Scheduled Mail Title", "Scheduled Mail Summary"))
.setRecurrency("0:0:0:1*12:0:0")
.setStartDate(new LocalDate(2012, 6, 5))
.setTimeZone("America/Los_Angeles")
.addToAddress("user_in_project@example.com")
.addBccAddress("another_user_in_project@example.com")
.setSubject("Mail subject")
.setBody("Mail body")
.addReportAttachment(reportDefinition,
Collections.singletonMap("pageOrientation", "landscape"),
pdf, xls)
);

Collection<Entry> result = md.find(project, ScheduledMail.class);
for (Entry e : result) {
ScheduledMail schedule = md.getObjByUri(e.getLink(), ScheduledMail.class);
}
```

### Dataset API

Upload data to datasets,..

```java
DatasetService datasetService = gd.getDatasetService();
datasetService.loadDataset(project, "datasetId", new FileInputStream("data.csv")).get();
```
Upload data to datasets using batch upload ,..

```java
DatasetService datasetService = gd.getDatasetService();
final DatasetManifest personManifest = datasetService.getDatasetManifest(project, "dataset.person");
personManifest.setSource(getClass().getResourceAsStream("/person.csv"));

final DatasetManifest cityManifest = datasetService.getDatasetManifest(project, "dataset.city");
cityManifest.setSource(getClass().getResourceAsStream("/city.csv"));

datasetService.loadDatasets(project, personManifest, cityManifest).get();
```

Update data in dataset
```java
DatasetService datasetService = gd.getDatasetService();
datasetService.updateProjectData(project, "DELETE FROM {attr.person.name} WHERE {label.person.name} = \"not exists\";");
```

### Report API

Execute and export reports.

```java
ReportService reportService = gd.getReportService();
reportService.exportReport(definition, PNG, new FileOutputStream("report.png")).get();
```

### DataStore API

Manage files on the data store (currently backed by WebDAV) - user staging area.

```java
DataStoreService dataStoreService = gd.getDataStoreService();
dataStoreService.upload("/dir/file.txt", new FileInputStream("file.txt"));
InputStream stream = dataStoreService.download("/dir/file.txt");
dataStoreService.delete("/dir/file.txt");
```

### Warehouse API
Manage warehouses - create, update, list and delete.
```java
WarehouseService warehouseService = gd.getWarehouseService();
Warehouse warehouse = warehouseService.createWarehouse(new Warehouse("title", "authToken", "description")).get();
String jdbc = warehouse.getJdbcConnectionString();

Collection<Warehouse> warehouseList = warehouseService.listWarehouses();
warehouseService.removeWarehouse(warehouse);
```

### Dataload processes API
Manage dataload processes - create, update, list, delete, and process executions - execute, get logs, schedules, ...
```java
ProcessService processService = gd.getProcessService();
DataloadProcess process = processService.createProcess(project, new DataloadProcess("name", "GRAPH"), new File("path/to/processdatadir"));

ProcessExecutionDetail executionDetail = processService.executeProcess(new ProcessExecution(process, "myGraph.grf")).get();
processService.getExecutionLog(executionDetail, new FileOutputStream("file/where/the/log/willbewritten"));

processService.createSchedule(project, new Schedule(process, "myGraph.grf", "0 0 * * *"));
```
## License
The *GoodData Java SDK* is free and open-source software under [BSD License](LICENSE.txt).

##Contribute
Missing functionality? Found a BUG?

Please create an [issue](https://github.com/martiner/gooddata-java/issues) or simply [contribute your code](CONTRIBUTING.md).
Missing functionality? Found a BUG? Please create an [issue](https://github.com/martiner/gooddata-java/issues)
or simply [contribute your code](CONTRIBUTING.md).

0 comments on commit 39af689

Please sign in to comment.