| Behavior | Version 2.x | Version 3.x
| Description |
|---|
|
Connection URL
|
The OpenKM application context is named OpenKM.
|
The OpenKM application context is named openkm (lowercase).
|
In version 2.x the connection URL is something like "http://localhost:8080/OpenKM"; in version 3.x it should be something like "http://localhost:8080/openkm".
|
|
Create new instance
|
The new instance is created with host, username, and password parameters.
|
The new instance is created with the host.
|
Because of a major change in the authentication architecture, instance creation is quite different. In version 2.x REST authentication uses basic authentication, which means each time an action is executed the SDK authenticates with a username and password. In version 3.x REST authentication supports several methods, such as basic and token. In version 3.x token authentication is used extensively. By default the token expires in 24 hours (see the documentation for more details about the login feature), and after the login method is executed the SDK will reuse the token for all actions.
Sample for version 2.x:
package com.openkm;
import com.openkm.sdk4j.OKMWebservices;
import com.openkm.sdk4j.OKMWebservicesFactory;
public class Test {
public static void main(String[] args) {
String host = "http://localhost:8080/OpenKM";
String username = "okmAdmin";
String password = "admin";
OKMWebservices ws = OKMWebservicesFactory.newInstance(host, username, password);
}
}
Sample for version 3.x:
package com.openkm;
import com.openkm.sdk4j.OKMWebservicesFactory;
import com.openkm.sdk4j.bean.Folder;
import com.openkm.sdk4j.impl.OKMWebservices;
public class Test {
public static void main(String[] args) {
String host = "http://localhost:8080/openkm";
String user = "okmAdmin";
String password = "admin";
OKMWebservices ws = OKMWebservicesFactory.getInstance(host);
try {
ws.login(user, password);
} catch (Exception e) {
e.printStackTrace();
}
}
}
|
|
Methods
|
All methods are in the parent class OKMWebservices.
|
The methods are in subclasses of OKMWebservices.
|
Because the SDK has more than 400 methods and was growing, having everything in the same parent became a little messy. That's why in version 3.x we decided to split methods based on their goal.
Methods related to document actions will be accessible from ws.document, and so on. In this manner, when you choose a method you can clearly identify its purpose.
The sample below shows how to create a folder with the ws.folder.createFolder method:
package com.openkm;
import com.openkm.sdk4j.OKMWebservicesFactory;
import com.openkm.sdk4j.bean.Folder;
import com.openkm.sdk4j.impl.OKMWebservices;
public class Test {
public static void main(String[] args) {
String host = "http://localhost:8080/openkm";
String user = "okmAdmin";
String password = "admin";
OKMWebservices ws = OKMWebservicesFactory.getInstance(host);
try {
ws.login(user, password);
Folder folder = ws.folder.createFolder("1be884f4-5758-4985-94d1-f18bfe004db8", "test");
System.out.println(folder);
} catch (Exception e) {
e.printStackTrace();
}
}
}
|
|
Nodes ID
|
In most methods you can use the path or the node UUID.
|
In most methods only the node UUID can be used.
|
This is a major improvement in the version 3.x API because it is not a good practice to use the path instead of the UUID.
The reason is that when working with the path, the OpenKM core must internally convert the path to the UUID, and this action consumes time and resources.
You can emulate the same behavior in version 3.x by converting the path to a UUID and then executing the action. But we encourage using only the UUID throughout the application.
Sample for version 2.x:
package com.openkm;
import com.openkm.sdk4j.OKMWebservices;
import com.openkm.sdk4j.OKMWebservicesFactory;
import com.openkm.sdk4j.bean.form.FormElement;
public class Test {
public static void main(String[] args) {
String host = "http://localhost:8080/OpenKM";
String username = "okmAdmin";
String password = "admin";
OKMWebservices ws = OKMWebservicesFactory.newInstance(host, username, password);
try {
for (FormElement fElement : ws.getPropertyGroupProperties("/okm:root/logo.pdf", "okg:consulting")) {
System.out.println(fElement);
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
How to simulate the behavior of version 2.x in version 3.x:
package com.openkm;
import com.openkm.sdk4j.OKMWebservicesFactory;
import com.openkm.sdk4j.impl.OKMWebservices;
public class Test {
public static void main(String[] args) {
String host = "http://localhost:8080/openkm";
String user = "okmAdmin";
String password = "admin";
OKMWebservices ws = OKMWebservicesFactory.getInstance(host);
try {
ws.login(user, password);
// Exists folder /okm:root/test
String uuid = ws.repository.getNodeUuid("/okm:root/test");
ws.folder.renameFolder(uuid, "renamedFolder");
// Folder has renamed to /okm:root/renamedFolder
} catch (Exception e) {
e.printStackTrace();
}
}
}
|
|
Create metadata
|
Two methods are needed to create metadata. The first is to add the empty group, and the second is to set the metadata values. |
There's a single method to add metadata groups and fields. |
In version 2.x it is required to execute two methods to add a metadata group. In version 3.x, with a single method execution, metadata groups and fields are added.
In version 2.x the values of the fields are set in a list of FormElement objects, meanwhile in version 3.x the values are stored in a map of pairs of the form (key, value).
Sample for version 2.x
package com.openkm;
import com.openkm.sdk4j.OKMWebservices;
import com.openkm.sdk4j.OKMWebservicesFactory;
public class Test {
public static void main(String[] args) {
String host = "http://localhost:8080/OpenKM";
String username = "okmAdmin";
String password = "admin";
OKMWebservices ws = OKMWebservicesFactory.newInstance(host, username, password);
try {
ws.addGroup("/okm:root/logo.pdf", "okg:consulting");
// Modify with a full FormElement list
List<FormElement> fElements = ws.getPropertyGroupProperties("/okm:root/logo.pdf","okg:consulting");
for (FormElement fElement : fElements) {
if (fElement.getName().equals("okp:consulting.name")) {
Input name = (Input) fElement;
name.setValue("new value");
}
}
ws.setPropertyGroupProperties("/okm:root/logo.pdf", "okg:consulting", fElements);
// Same modification with only affected FormElement
fElements = new ArrayList<>();
Input name = new Input();
name.setName("okp:consulting.name");
name.setValue("new value");
fElements.add(name);
ws.setPropertyGroupProperties("/okm:root/logo.pdf","okg:consulting", fElements);
} catch (Exception e) {
e.printStackTrace();
}
}
}
Sample for version 3.x
package com.openkm;
import java.util.Calendar;
import java.util.HashMap;
import java.util.Map;
import com.openkm.sdk4j.OKMWebservicesFactory;
import com.openkm.sdk4j.impl.OKMWebservices;
import com.openkm.sdk4j.util.ISO8601;
public class Test {
public static void main(String[] args) {
String host = "http://localhost:8080/openkm";
String user = "okmAdmin";
String password = "admin";
OKMWebservices ws = OKMWebservicesFactory.getInstance(host);
try {
ws.login(user, password);
Map<String, String> propertiesMap = new HashMap<>();
propertiesMap.put("okp:consulting.name", "new name");
// Date fields must be saved with basic ISO 8601 format
propertiesMap.put("okp:consulting.date", ISO8601.formatBasic(Calendar.getInstance()));
propertiesMap.put("okp:consulting.comment", "new comment");
ws.propertyGroup.addPropertyGroup("8cd1e072-8595-4dd3-b121-41d622c43f08", "okg:consulting", propertiesMap);
} catch (Exception e) {
e.printStackTrace();
}
}
}
|
|
Get metadata
|
Returns a list of FormElement objects |
Returns a map of pairs of the form (key, value) |
In version 2.x the metadata values are returned in a list of FormElement objects. If you build a user interface with metadata fields, the main advantage of version 2.x is that values and field information are returned in the same call. In version 3.x the values are returned in a map of pairs of the form (key, value). The main advantage of version 3.x is that it returns only the information you need ? the values ? not additional information like field type, etc., which is only required for rendering in the user interface. If you need rendering information, there is another specific method that retrieves the FormElement list; it must be used in combination with the metadata values. In terms of performance, version 3.x is faster than 2.x.
Sample for version 2.x:
package com.openkm;
import com.openkm.sdk4j.OKMWebservices;
import com.openkm.sdk4j.OKMWebservicesFactory;
import com.openkm.sdk4j.bean.form.FormElement;
public class Test {
public static void main(String[] args) {
String host = "http://localhost:8080/OpenKM";
String username = "okmAdmin";
String password = "admin";
OKMWebservices ws = OKMWebservicesFactory.newInstance(host, username, password);
try {
for (FormElement fElement : ws.getPropertyGroupProperties("/okm:root/logo.pdf", "okg:consulting")) {
System.out.println(fElement);
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Sample for version 3.x:
package com.openkm;
import java.util.HashMap;
import java.util.Map;
import com.openkm.sdk4j.OKMWebservicesFactory;
import com.openkm.sdk4j.impl.OKMWebservices;
public class Test {
public static void main(String[] args) {
String host = "http://localhost:8080/openkm";
String user = "okmAdmin";
String password = "admin";
OKMWebservices ws = OKMWebservicesFactory.getInstance(host);
try {
ws.login(user, password);
Map<String, String> properties = new HashMap<>();
properties = ws.propertyGroup.getPropertyGroupProperties("8cd1e072-8595-4dd3-b121-41d622c43f08", "okg:technology");
for (String key : properties.keySet()) {
System.out.println(key + " > " + properties.get(key));
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
|
