Migration from 2.x to 3.x

Entre las versiones 2.x y 3.x hay muchos cambios. La mayoría están relacionados con la refactorización de nombres de métodos o con variables añadidas/eliminadas en algunas clases. La tabla siguiente muestra los principales cambios que debe tener en cuenta antes de planificar la migración de la versión 2.x a la 3.x.

Comportamiento	Versión 2.x	Versión 3.x	Descripción
URL de conexión	El contexto de la aplicación OpenKM se llama OpenKM.	El contexto de la aplicación OpenKM se llama openkm (en minúsculas).	En la versión 2.x la URL de conexión es algo como “http://localhost:8080/OpenKM”; en la versión 3.x debería ser algo como “http://localhost:8080/openkm”.

Crear una nueva instancia

Versión 2.x

La nueva instancia se crea con los parámetros host, username y password.

Versión 3.x

La nueva instancia se crea con el host.

Descripción

Debido a un cambio importante en la arquitectura de autenticación, la creación de la instancia es bastante diferente. En la versión 2.x la autenticación REST usa autenticación básica, lo que significa que cada vez que se ejecuta una acción el SDK se autentica con un usuario y una contraseña. En la versión 3.x la autenticación REST admite varios métodos, como básica y por token. En la versión 3.x se usa extensamente la autenticación por token. Por defecto el token expira a las 24 horas (consulte la documentación para más detalles sobre la funcionalidad de login), y tras ejecutar el método login el SDK reutilizará el token para todas las acciones.

Ejemplo para la versión 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);
    }
}

Ejemplo para la versión 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();
        }
    }
}

Métodos

Versión 2.x

Todos los métodos están en la clase padre OKMWebservices.

Versión 3.x

Los métodos están en subclases de OKMWebservices.

Descripción

Dado que el SDK tiene más de 400 métodos y seguía creciendo, tener todo en el mismo padre se volvió un poco confuso. Por eso en la versión 3.x decidimos dividir los métodos según su propósito.

Los métodos relacionados con acciones sobre documentos estarán accesibles desde ws.document, y así sucesivamente. De este modo, al elegir un método puede identificar claramente su propósito.

El siguiente ejemplo muestra cómo crear una carpeta con el método ws.folder.createFolder:

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();
        }
    }
}

ID de los nodos

Versión 2.x

En la mayoría de los métodos puede usar el path o el UUID del nodo.

Versión 3.x

En la mayoría de los métodos solo puede usarse el UUID del nodo.

Descripción

Esta es una mejora importante en la API de la versión 3.x, porque no es una buena práctica usar el path en lugar del UUID.

El motivo es que al trabajar con el path, el núcleo de OpenKM debe convertir internamente el path al UUID, y esa acción consume tiempo y recursos.

Puede emular el mismo comportamiento en la versión 3.x convirtiendo el path a un UUID y ejecutando después la acción. Pero le recomendamos usar únicamente el UUID en toda la aplicación.

Ejemplo para la versión 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();
        }
    }
}

Cómo simular en la versión 3.x el comportamiento de la versión 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();
        }
    }
}

Crear metadatos

Versión 2.x

Se necesitan dos métodos para crear metadatos. El primero para añadir el grupo vacío, y el segundo para establecer los valores de los metadatos.

Versión 3.x

Existe un único método para añadir grupos y campos de metadatos.

Descripción

En la versión 2.x es necesario ejecutar dos métodos para añadir un grupo de metadatos. En la versión 3.x, con la ejecución de un único método, se añaden los grupos y campos de metadatos.

En la versión 2.x los valores de los campos se establecen en una lista de objetos FormElement, mientras que en la versión 3.x los valores se almacenan en un mapa de pares (clave, valor).

Ejemplo para la versión 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();
        }
    }
}

Ejemplo para la versión 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();
        }
    }
}

Obtener metadatos

Versión 2.x

Devuelve una lista de objetos FormElement

Versión 3.x

Devuelve un mapa de pares (clave, valor)

Descripción

En la versión 2.x los valores de los metadatos se devuelven en una lista de objetos FormElement. Si construye una interfaz de usuario con campos de metadatos, la principal ventaja de la versión 2.x es que los valores y la información de los campos se devuelven en la misma llamada. En la versión 3.x los valores se devuelven en un mapa de pares (clave, valor). La principal ventaja de la versión 3.x es que devuelve solo la información que necesita —los valores— y no información adicional como el tipo de campo, etc., que solo es necesaria para renderizar en la interfaz de usuario. Si necesita información de renderizado, existe otro método específico que recupera la lista de FormElement; debe usarse junto con los valores de los metadatos. En términos de rendimiento, la versión 3.x es más rápida que la 2.x.

Ejemplo para la versión 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();
        }
    }
}

Ejemplo para la versión 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();
        }
    }
}