Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Move usage doc from README to wiki #191

Merged
merged 1 commit into from
Jun 17, 2015
+26 −187
Merged

Move usage doc from README to wiki #191

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 18 additions & 9 deletions CONTRIBUTING.md
View file
Open in desktop
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
Open in desktop
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).