| Behavior | Version 1.x | Version 2.x
| Description |
|---|
|
Connection URL
|
The OpenKM application context is named OpenKM.
|
The OpenKM application context is named openkm (lowercase).
|
In version 1.x the connection URL is something like "http://localhost:8080/OpenKM"; in version 2.x you should use 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 1.x REST authentication uses basic authentication, which means each time an action is executed the SDK authenticates with a username and password. In version 2.x REST authentication supports several procedures, such as basic and token authentication. In version 2.x token authentication is used extensively. The token, by default, expires in 24 hours (take a look in the documentation for more details about the login feature), and after the login method is executed the SDK will reuse the token for all subsequent actions.
Sample for version 1.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 2.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
|
In version 1.x all methods are in the OKMWebservices class.
|
In version 2.x the methods are organized into subclasses under OKMWebservices.
|
Because the SDK has more than 400 methods and was growing, having everything in the same parent became a bit of a mess. That's why in version 2.x they decided to split methods based on their purpose.
Methods related to document actions will be accessible from ws.document, etc. 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 2.x API because it is not good practice to use paths instead of UUIDs.
The reason is that when working with a path the OpenKM core must convert the path to a UUID internally, and this action consumes processing time and resources.
You can emulate the same behavior in version 2.x by converting the path to a UUID and then executing the action. However, we encourage using only UUIDs throughout the application.
Sample for version 1.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 1.x in version 2.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 to set the metadata values. |
There's a single method to add metadata groups and fields. |
In version 1.x it is necessary to execute two methods to add a metadata group. In version 2.x, a single method call adds metadata groups and fields.
In version 1.x the values of the fields are set in a list of FormElement objects, whereas in version 2.x the values go into a map of (key, value) pairs.
Sample for version 1.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 2.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 (key, value) pairs |
In version 1.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 1.x is that values and field information are returned in the same call. In version 2.x the values are returned in a map of (key, value) pairs. The main advantage of version 2.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 2.x is faster than 1.x.
Sample for version 1.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 2.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();
}
}
}
|
