Vikadata™ Java SDK (vika.java)
Java Client Library for the Vika OpenAPI

Vika Java SDK

Vikadata™ Java API (vika.java) provides a full featured and easy to consume Java library for working with vikadata via the Vikadata OpenAPI.

---

Usage

Java Version Requirement

Java 8+ is required to use sdk. not support Java 8 below

Getting Started

Installation

• Maven

<dependency>
<groupId>cn.vika</groupId>
<artifactId>vika-client</artifactId>
<version>1.0.4</version>
</dependency>

• Gradle

dependencies {
... ...
implementation('cn.vika:vika-client:1.0.4')
}

Usage Example

vika java sdk is quite simple to use, you don't need to set api url, all you need is the Personal Api Key from your vika account settings page. Once you have that info it is as simple as:

First, you need to set api credential which belong your personal api key.

ApiCredentialcredential = newApiCredential("Your API Key");

Then, Init client instance

VikaApiClientvikaApiClient = newVikaApiClient(credential);

By default, the API client has been added for setting connect and read timeouts, you can also change:

// Set the connect timeout to 8 second and the read timeout to 9 secondsVikaApiClientvikaApiClient = newVikaApiClient(credential)
.withRequestTimeout(80000)
.withReadTimeout(90000);

As private deployment user, you can also change host url

VikaApiClientvikaApiClient = newVikaApiClient("http://ip:port", credential);

Query Record

Most simple usage for query record quickly

// Get 10 records on first pageList<Record> records = vikaApiClient.getRecordApi().getRecords("datasheetId", 1, 10);

Pager Resulting

API client provides an easy way to use paging mechanism to page through lists of results from the Open API. Below code are a couple of examples on how to use the Pager:

// Get a Pager instance that will page through the records with 100 record per pagePager<Record> pager = vikaApiClient.getRecordApi().getRecords("datasheet_id", 100);
// Iterate through the pages and print out the per record detailwhile (pager.hasNext()) {
for (Recordrecord : pager.next()) {
System.out.println(record.getRecordId() + " -: " + record.getFields());
}
}

you can also fetch all the items as a single list using a Pager instance:

// Get a Pager instance so we can load all the records into a single list, 100 record at a time:Pager<Record> pager = vikaApiClient.getRecordApi().getRecords("datasheet_id", 100);
List<Record> records = pager.all();

Java 8 Stream Support

also provide method that returns a Java 8 Stream.

// Pager as stream,support forEach、Group、Filter operationStream<Record> records = vikaApiClient.getRecordApi().getRecordsAsStream("datasheet_id");
// ex: extract record id to a listrecords.map(Record::getRecordId).collect(Collectors.toList());

Advance Query

// build query conditionApiQueryParamqueryParam = newApiQueryParam(1, 50)
.withView("viewId")
.withFields(Arrays.asList("fieldName"))
.withRecordIds(Arrays.asList("recordId"))
.withSort("fieldName", Order.DESC).withSort("fieldName", Order.ASC)
.withFilter("{fieldName}>1");
// query return pager resultPager<Record> pager = vikaApiClient.getRecordApi().getRecords("datasheet_id", queryParam);

Add Record

Class RecordMap is a key-value structure like Map<String, Object>, all thing you do is converting json to map, you can use convert util from sdk provide which is named JacksonConverter, you also can use jackson api build json structure data, more detail please reference unit test.

you can add record through two difference way, id or name, default is name fieldKey.

using default fieldKey name example:

// Build Record Map by jackson apiObjectNodefieldMap = JsonNodeFactory.instance.objectNode()
// simple data
.put("fieldName", "string")
.put("number", 1234);
// sub tree node
.set("city", JsonNodeFactory.instance.arrayNode().add("NewYork").add("Bejing"));
// put record map into fields keyObjectNodefields = JsonNodeFactory.instance.objectNode().set("fields", fieldMap);
// only one record, warp record into array nodeArrayNodearrayNode = JsonNodeFactory.instance.arrayNode().add(fields);
// convert json to Map ListList<RecordMap> recordMaps = JacksonConverter.unmarshalToList(RecordMap.class, arrayNode);
// create record requestCreateRecordRequestrecordRequest = newCreateRecordRequest()
.withRecords(recordMaps);
// okList<Record> newRecords = vikaApiClient.getRecordApi().addRecords("datasheet_id", recordRequest);

using fieldKey id example:

// Build Record Map by jackson apiObjectNodefieldMap = JsonNodeFactory.instance.objectNode()
// simple data
.put("fld_id", "string")
.put("fld_id", 1234);
// sub tree node
.set("fld_id", JsonNodeFactory.instance.arrayNode().add("NewYork").add("Bejing"));
// put record map into fields keyObjectNodefields = JsonNodeFactory.instance.objectNode().set("fields", fieldMap);
// only one record, warp record into array nodeArrayNodearrayNode = JsonNodeFactory.instance.arrayNode().add(fields);
// convert json to Map ListList<RecordMap> recordMaps = JacksonConverter.unmarshalToList(RecordMap.class, arrayNode);
// create record requestCreateRecordRequestrecordRequest = newCreateRecordRequest()
.withRecords(recordMaps)
.withFieldKey(FieldKey.ID);
// okList<Record> newRecords = vikaApiClient.getRecordApi().addRecords("datasheet_id", recordRequest);

Update Record

update record also provide two difference way to modifying data, using fieldKey id or name, default is name fieldKey.

using default fieldKey name example:

// Build update record modelUpdateRecordrecord = newUpdateRecord()
// row record id from query result or add record result
.withRecordId("recXXXXX")
// single-text type field cell
.withField("SingleText", "ABC")
// single-select type field cell,// it can be set null or empty array if you want to clear field value: withField("Options", null)
.withField("Options", Arrays.asList("LL", "NN"));
// new Request modelUpdateRecordRequestupdateRecordRequest = newUpdateRecordRequest()
.withRecords(Collections.singletonList(record));
// request sendList<Record> updateRecords = vikaApiClient.getRecordApi().updateRecords("datasheet_id", updateRecordRequest);

using fieldKey id example:

// Build update record modelUpdateRecordrecord = newUpdateRecord()
// row record id from query result or add record result
.withRecordId("recXXXXX")
// single-text type field cell
.withField("fld_id", "ABC")
// single-select type field cell,// it can be set null or empty array if you want to clear field value: withField("Options", null)
.withField("fld_id", Arrays.asList("LL", "NN"));
// new Request modelUpdateRecordRequestupdateRecordRequest = newUpdateRecordRequest()
.withRecords(Collections.singletonList(record))
.withFieldKey(FieldKey.ID);
// request sendList<Record> updateRecords = vikaApiClient.getRecordApi().updateRecords("datasheet_id", updateRecordRequest);

Delete Record

// DELETE one record onlyvikaApiClient.getRecordApi().deleteRecord("datasheet_id", "recXXXXXX");
// DELETE many recordvikaApiClient.getRecordApi().deleteRecords("datasheet_id", Arrays.asList("recXXXXXX", "recXXXXXX"));
// Delete all records, may be slowly work if sheet have large recordsvikaApiClient.getRecordApi().deleteAllRecords("datasheet_id");

Upload Attachment

sdk provide several way to upload attachment, You can choose the way to upload anything that suits you

// classPath resource on src/main/resource/test.txtResourceLoaderclassPathResource = newClassPathResourceLoader("test.txt");
Attachmentattachment = vikaApiClient.getAttachmentApi().upload("datasheet_id", classPathResource);
// or url resource from webResourceLoaderurlResource = newUrlResourceLoader(UrlUtil.url("https://test.com/image.png"))
Attachmentattachment = vikaApiClient.getAttachmentApi().upload("datasheet_id", urlResource);
// or file resourceFilefile = newFile("/Users/Document/test.txt");
Attachmentattachment = vikaApiClient.getAttachmentApi().upload("datasheet_id", newFileResourceLoader(file));
// or upload file type directlyFilefile = newFile("/Users/Document/test.txt");
Attachmentattachment = vikaApiClient.getAttachmentApi().upload("datasheet_id", file);

Add Field

You can create field by sdk. Firstly, we need to build the property required by the field. Secondly, Using CreateFieldRequestBuilder to creating a CreateFieldRequest object. Finally, submitting the request to the specified space and the specified datasheet. If creating the field successfully, we can get the new field's id and name.

more detail about field type and property of field see official API manual#create-field

create single text field example:

// build the SingleText field's propertySingleTextFieldPropertysingleTextFieldProperty = newSingleTextFieldProperty();
singleTextFieldProperty.setDefaultValue("defaultValue");
// create a CreateFieldRequest ObjectCreateFieldRequest<SingleTextFieldProperty> createFieldRequest = CreateFieldRequestBuilder
.create()
.ofType(FieldTypeEnum.SingleText)
.withName("singleText")
.withProperty(singleTextFieldProperty)
.build();
// request to create a fieldCreateFieldResponseresponse = vikaApiClient.getFieldApi().addField("space_id", "datasheet_id", createFieldRequest);

create text field example:

// if field don't require property, we can skip the process that build the propertyCreateFieldRequest<EmptyProperty> createFieldRequest = CreateFieldRequestBuilder
.create()
.ofType(FieldTypeEnum.Text)
.withName("text")
.withoutProperty()
.build();
// request to create a fieldCreateFieldResponsecreateFieldRequest = vikaApiClient.getFieldApi().addField("space_id", "datasheet_id", createFieldRequest);

Detele Field

// we can use field_id to detele fieldvikaApiClient.getFieldApi().deleteField("space_id", "datasheet_id", "field_id");

Add Datasheet

You can create a datasheet with the help of a CreateDatasheetRequest Object. If creating the datasheet successfully, we can get the new datasheet's id, name and the fields' id, name.

more detail see official API munual#create-datasheet

// create a CreateDatasheetRequest ObjectCreateDatasheetRequestcreateDatasheetRequest = newCreateDatasheetRequest();
// datasheet's name is required.request.setName("datasheet");
// add description to datasheetrequest.setDescription("description");
// specify the folder where the datasheet is storedrequest.setFolderId("fold_id");
// specify the datasheet's previous noderequest.setPreNodeId("pre_node_id");
// datasheet's initial fieldsSingleTextFieldPropertyproperty = newSingleTextFieldProperty();
property.setDefaultValue("defaultValue");
// a SingleText fieldCreateFieldRequest<SingleTextFieldProperty> singleSelectField = CreateFieldRequestBuilder
.create()
.ofType(FieldTypeEnum.SingleText)
.withName("singleSelect")
.withProperty(property)
.build();
// a Text fieldCreateFieldRequest<EmptyProperty> textField = CreateFieldRequestBuilder
.create()
.ofType(FieldTypeEnum.Text)
.withName("text")
.withoutProperty()
.build();
List<CreateFieldRequest<?>> fields = newArrayList<>();
fields.add(singleSelectField);
fields.add(textField);
request.setFields(fields);
// request to create a datasheetCreateDatasheetResponseresponse = vikaApiClient.getDatasheetApi().addDatasheet("space_id", createDatasheetRequest);

Reporting Issues

Vika java sdk project uses GitHub's integrated issue tracking system to record bugs and feature requests. If you want to raise an issue, please follow the recommendations below:

• Before you log a bug, please search the issue tracker to see if someone has already reported the problem.
• If the issue doesn't already exist, create a new issue.
• Please provide as much information as possible with the issue report, we like to know the version that you are using, as well as your Operating System and JVM version.
• If you need to paste code, or include a stack trace use Markdown escapes before and after your text.

License

Open Source software released under the MIT License.