# API Client for Java Usage

cytomine/Cytomine-java-client | Last release: v2.1.0

# Connection

The first step with the use of a Cytomine client is to authenticate you to the Cytomine instance that you want to interact with.
This authentication is made with 3 arguments :

  • The URL of the Cytomine instance;
  • The public key of a user;
  • The private key of a user.

These keys can be found in your Account page on your Cytomine instance. In the Java client it's done with connection static method of the Cytomine class:

    Cytomine.connection(cytomineCoreUrl, publickey, privatekey);
1

# Model

As Cytomine is a project following the Object Oriented Paradigm (opens new window), it is built on basic element called objects, domains or models. In Cytomine, users, projects, annotations or images are objects.
In our external clients, these objects are called models and each object in Cytomine have its model representation (a class) in the external clients. Each object (an instance of model):

  • has a set of attributes corresponding to resource attributes
  • is managed itself through fetch(), save(), update() and delete() methods that communicate with the Cytomine-core server
  • has some utilities to be serialized to JSON

Technically, all models inherits from a parent class Model that encapsulate functions as save(), update(), delete(), get_url(), etc.

    //in Java
    //creation of a project
    Long ontID = 0L;
    Ontology ontology = new Ontology().fetch(ontID);
    String name = "test";
    Project p = new Project(name,ontology).save();
    //fetch a project
    Long projectID = 0L;
    Project p = new Project().fetch(projectID);
    //update a project
    p.set("name", name+"bis");
    p.update();
    //delete a project
    p.delete();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Supplementary actions

In some cases, the server provides supplementary actions for some resources. These actions are encapsulated in additional methods for the model (downloading an ImageInstance, uploading an attached file, ...).

# Collection

A Collection is a representation of a collection of models.
This class contains methods that allow you to fetch multiples models with filters and/or pagination (with max and offset parameters).
You can use the Collection class directly with a Model:

    Collection c = new Collection<>(ImageInstance.class);
    c.addFilter("project", project.getId().toString());
    c.fetch(); // will return all the image instance into the projectCollection
    c = new Collection<>(ImageInstance.class, 0,2);
    c.addFilter("project", project.getId().toString());
    c.fetch(); // will return the two first image instances into the project
1
2
3
4
5
6

However, there is specific class in some case:

    ImageInstanceCollection.fetchByProject(project); // will return all the image instance into the project
    ImageInstanceCollection.fetchByProject(project,0,2); // will return the two first image instances into the project
1
2

Usually, a specific class is created for :

  • specific methods related to these models collection;
  • syntaxic sugar;
Last Updated: 5/3/2021, 7:19:51 PM