Libertya Web Services

Generalidades, instalación y uso

Indice

• Libertya Web Services 
  • Generalidades, instalación y uso 
• Indice 
• Objetivos de este documento 
• Prerequisitos 
• Instalación del servicio 
• Acceso al Servicio 
• Mecanismo de Interacción 
  • ParameterBean y Result Bean 
  • Jerarquía de clases 
  • Log de Ejecución 
  • Parámetros y Argumentos de la invocación 
• LibertyaWSE 

Objetivos de este documento

El presente documento explica la forma de acceder al Servicio Web Libertya y brinda el detalle de los métodos y parámetros requeridos en cada caso. Además presenta ejemplos de uso y funcionalidades adicionales como es la generación del archivo de log de invocaciones y errores.

Prerequisitos

En términos generales, la versión más reciente de LYWS siempre se apoya en la version más reciente de Libertya CORE. De todas maneras, es probable que sea parcialmente compatible con versiones anteriores de Libertya.

Instalación del servicio

Descomprimir el ZIP con nombre org.libertya.ws.rXXSF.zip (donde XX es un número que varía en cada release de LYWS) dentro del directorio:

• OXP_HOME/jboss/server/openXpertya/deploy/

Donde OXP_HOME refiere al directorio raiz de Libertya (generalmente llamado ServidorOXP). Como resultado, dentro del directorio deploy se debería haber creado el directorio axis.war:

• OXP_HOME/jboss/server/openXpertya/deploy/axis.war

Recordar que para estas acciones es necesario contar con los correspondientes permisos de escritura sobre el directorio en cuestión.

Acceso al Servicio

Accediendo desde el navegador a:

• http://SERVIDOR_LIBERTYA:PUERTO_LIBERTYA/axis/servlet/AxisServlet

(donde SERVIDOR_LIBERTYA es el hostname del equipo y PUERTO_LIBERTYA es el puerto de JBoss configurado al ejecutar Configurar.sh o Configurar.bat), se pueden observar los servicios actualmente implementados.

Desde un cliente Java, la URL de conexión al Web Service es la siguiente:

• http://SERVIDOR_LIBERTYA:PUERTO_LIBERTYA/axis/services/LibertyaWS

El acceso a los servicios desde Java es sencillo debido a las clases de soporte para el cliente que se entregan para este fin. Suponiendo que el Servidor de Aplicaciones de Libertya se encuentra en 192.168.0.10:8080, el código para el acceso al WS de Libertya es:

// Conexión al WS
LibertyaWSServiceLocator locator = new LibertyaWSServiceLocator(); locator.setLibertyaWSEndpointAddress(“http://192.168.0.10:8080/axis/services/LibertyaWS”);
// Recuperación del Servicio
ws.libertya.org.LibertyaWS lyws = locator.getLibertyaWS();
// Invocación de ejempo a eliminación de factura
ResultBean result = lyws.invoiceDeleteByID(…);

Las clases LibertyaWSServiceLocator, LibertyaWS y las restantes clases necesarias para el acceso y uso del WS de Libertya son proporcionadas junto con la presente documentación. La clase org.libertya.ws.client.LibertyaWSClient contiene varios ejemplos de uso.

Mecanismo de Interacción

En la interacción con el WS por parte del cliente se invoca a uno de los servicios en cuestión, pasando los parámetros correspondientes, los cuales se encuentran encapsulados en una jerarquía de clases de parámetros cuya superclase es ParameterBean. Luego de procesar, el WS devolverá la respuesta con el mismo criterio, en este caso la superclase de resultados es ResultBean.

ParameterBean y Result Bean

Cada invocación a un servicio requiere la carga previa de un conjunto de datos necesarios para la ejecución de los servicios.

Los datos a cargar varían dependiendo la operación, aunque hay una serie de datos obligatoria en todos los casos, que son: Nombre de usuario, Contraseña, Compañía, Organización (la cual puede ser 0).

Las subclases de ParameterBean contienen información adicional específica. Por ejemplo: BPartnerParameterBean contendrá información de la dirección de la Entidad Comercial, e InvoiceParameterBean contendrá información sobre las líneas de una factura.

De manera análoga, se obtendrá una clase ResultBean (o alguna de sus subclases) con los resultados de la operación.

Jerarquía de clases

Se muestra a continuación una parte de la jerarquía de parámetros y resultados:

• Object
  
• ­­ParameterBean
  • ­­BPartnerParameterBean
    
  • ­­DocumentParameterBean
    • ­­InvoiceParameterBean
      
• ­­ResultBean
  • ­­BPartnerResultBean
    
  • DocumentResultBean
    
  • ­­MultipleDocumentsResultBean

ParameterBean contiene los miembros generales a pasar como parámetro, tal como compañía, usuario, password, y los datos a cargar para la tabla principal (ésta dependiendo el WS en el que estemos: si es el WS de Entidades Comerciales será la tabla C_BPartner, si es de facturas será la tabla C_Invoice, etc.):

/** Usuario LY */
protected String userName = "“;
/** Contraseña LY */
protected String password =”";
/** Compañía a acceder */
protected int clientID = 0;
/** Organización */
protected int orgID = 0;
/** Coleccion para la tabla principal */
protected HashMap<String, String> mainTable = new HashMap<String, String>();

Los datos a cargar en la tabla en cuestión se reciben como pares: <nombre de columna, dato>. De esta manera no es necesario modificar el WS en caso de que posteriormente se modifique el número de columnas de una tabla, simplemente se envía un par adicional desde el cliente.

Las subclases amplían esta estructura con información adicional según corresponda. Por ejemplo para Entidades Comerciales, es necesario contar con información relacionada a su dirección. Las facturas / pedidos / remitos tendrán las líneas, etc. Cada subclase presenta métodos para hacer más intuitiva la carga de parámetros desde el cliente, con invocaciones independientes para cada tabla.

/**
* Incorpora una nueva columna a los datos de parámetro la E.C.
* @param columnName nombre de la columna
* @param columnValue valor de la columna
*/
public void addColumnToBPartner(String columnName, String columnValue) { … }

/**
* Incorpora una nueva columna a los datos de parámetro de dirección de la E.C.
* @param columnName nombre de la columna
* @param columnValue valor de la columna
*/
public void addColumnToLocation(String columnName, String columnValue) { … }

La jerarquía de resultados es similar. La superclase ResultBean contiene los miembros:

/** El resultado fue un error */
protected boolean error = false;
/** Mensaje de error */
protected String errorMsg = "";
/** Valores de retorno principales o de tabla principal */
protected HashMap<String, String> mainResult = new HashMap<String, String>();

Luego las subclases amplían la información a devolver, por ejemplo BPartnerResultBean contiene información inherente a este WS según los requerimientos, tal como dirección de facturación, usuario de contacto, etc.

/** Valores de retorno de la última dirección de facturación */
protected HashMap<String, String> billAddress = new HashMap<String, String>();
/** Indica si existen más direcciones */
boolean modeAddresses = false;
/** Valores de retorno del contacto más nuevo */
protected HashMap<String, String> userContact = new HashMap<String, String>();

Desde el cliente se instancian entonces estas clases de parámetros, se asignan los valores y luego se invoca al servicio, pasándo como parámetro este objeto (además de otros datos según corresponda).

Notar que dependiendo el servicio se recibe/devuelve una especialización o una generalización en la jerarquía (no en todos los casos hacemos uso de las hojas de la jerarquía). Esto hace más fácil la interpretación de qué parámetros se deben enviar en cada caso y qué datos obtendremos como resultado.

Log de Ejecución

Toda ejecución de una acción o error queda persistida en el log con el siguiente formato:

Fecha y Hora, [INFO|WS_ERROR|MODEL_ERROR] (Usuario) – Datos específicos de cada ejecución.

Dicho archivo de log se llama lyws.log y se escribirá en la ubicación especificada en la variable de entorno OXP_WS_LOG. Si dicha variable no se encuentra especificada, utilizará por defecto la variable de entorno OXP_HOME de la aplicación (comunmente /ServidorOXP en instalaciones Linux, y C:\ServidorOXP en Windows). Tener en cuenta que es necesario contar con los permisos correspondientes en el directorio en cuestión para que el WS de Libertya pueda escribir el archivo.

Ejemplo:

2012-08-05 14:20:40 [INFO] (AdminLibertya) - org.libertya.ws.handler.InvoiceDocumentHandler - Ejecutando invoiceDelete
2012-08-05 14:20:40 [MODEL_ERROR] (AdminLibertya) - org.libertya.ws.handler.InvoiceDocumentHandler - org.libertya.ws.exception.ModelException: No se pudo recuperar un registro para la tabla C_Invoice con los criterios especificados. (org.libertya.ws.handler.GeneralHandler.getPO(GeneralHandler.java:508), org.libertya.ws.handler.InvoiceDocumentHandler.invoiceDelete(Unknown Source)…
2012-08-05 14:20:40 [INFO] (AdminLibertya) - org.libertya.ws.handler.BPartnerCRUDHandler - Ejecutando
bPartnerCreate
2012-08-05 14:20:41 [MODEL_ERROR] (AdminLibertya) - org.libertya.ws.handler.BPartnerCRUDHandler -
org.libertya.ws.exception.ModelException: Error al persistir entidad comercial:Could not save changes: : Existe un
registro de Entidad Comercial que ya contiene el valor value188 para el campo Clave. El valor de este campo no
puede ser duplicado. (org.libertya.ws.handler.BPartnerCRUDHandler.bPartnerCreate(Unknown Source)…
2012-08-05 14:20:41 [INFO] (AdminLibertya) - org.libertya.ws.handler.BPartnerCRUDHandler - Ejecutando
bPartnerRetrieve
2012-08-05 14:20:41 [INFO] (AdminLibertya) - org.libertya.ws.handler.InvoiceDocumentHandler - Ejecutando
invoiceCreateCustomer

En el ejemplo primeramente se está invocando a invoiceDelete, posteriormente se indica un error de modelo (no se encuentra la factura en cuestión), luego se intenta crear una entidad comercial mediante bPartnerCreate, y posteriormente un error de modelo indicando que ya existe una entidad comercial con la clave de búsqueda especificada. Por último se invoca a la recuperación de una entidad comercial y la creación de una factura.

Parámetros y Argumentos de la invocación

Adicionalmente al stack de error informativo, se incorpora en el log el conjunto de parámetros enviados en el ParameterBean correspondiente, así como los argumentos adicionales que completan la firma del método invocado; indicados mediante Parameters y Method Arguments correspondientemente.

Un ejemplo se muestra a continuación:

ERROR. java.lang.Exception: Error de acceso para usuario AdminLibertya
(org.libertya.ws.handler.GeneralHandler.checkLogin(GeneralHandler.java:133),
org.libertya.ws.handler.GeneralHandler.init(GeneralHandler.java:73),
org.libertya.ws.handler.AllocationDocumentHandler.allocationCreateReceipt(AllocationDocumentHandler.java:75),
org.libertya.ws.handler.AllocationDocumentHandler.allocationCreateReceipt(AllocationDocumentHandler.java:46),
org.libertya.ws.LibertyaWSImpl.allocationCreateReceipt(LibertyaWSImpl.java:324),
org.libertya.ws.client.LibertyaWSClient.main(LibertyaWSClient.java:337))
- Parameters -
org.libertya.ws.bean.parameter.AllocationParameterBean - UserName = AdminLibertya;
ClientID = 1010016; OrgID = 1010053
mainTable: Description = Un RC desde WS;
Invoices:
Amount = 350; C_Invoice_ID = 1021694;
Payments:
Amount = 70; C_POSPaymentMedium_ID = 1010038; C_Invoice_ID = 1021695;
TransferNo = 1234; Amount = 30; C_POSPaymentMedium_ID = 1010034; TransferDate = 2012-
09-03 10:20:00; C_BankAccount_ID = 1010071;
Amount = 20; CreditCardNumber = 102929281810; C_POSPaymentMedium_ID = 1010036; A_Bank
= Comafi; CouponNumber = 12341234; M_EntidadFinancieraPlan_ID = 1010033;
Amount = 40; C_POSPaymentMedium_ID = 1010037; DateTrx = 2012-09-03 10:26:15; DueDate
= 2012-09-04 10:26:15; CheckNo = 12345; C_BankAccount_ID = 1010070;
Amount = 40; C_POSPaymentMedium_ID = 1010033; C_Cash_ID = 1010062;
Amount = 70; C_CashLine_ID = 1010100; C_POSPaymentMedium_ID = 1010035;
C_Payment_ID = 1011960; Amount = 30; C_POSPaymentMedium_ID = 1010035;
Amount = 50; C_POSPaymentMedium_ID = 1010039; Retenc_Date = 2012-09-04 10:44:18;
Retenc_DocumentNo = 5311181; C_RetencionSchema_ID = 1010054;
- Method arguments: bPartnerID = -1; bPartnerValue = MC; taxID = null; isEarlyPayment =
false;

LibertyaWSE

Si bien LYWS simplifica considerablemente la gestión de parámetros/resultados desde Java gracias a la jerarquía de Beans (Parameters & Results), el manejo desde otras tecnologías puede llegar a requerir el uso de estructuras más tradicionales.

Es por ésto que se ha definido un conjunto de wrappers bajo LYWSE para el total de los servicios de LYWS, los cuales presentan una gestión de argumentos con tipos primitivos dentro del contexto de Servicios Web.

Las operaciones incluidas en LYWSE son por lo tanto exactamente las mismas que para LYWS; variando únicamente los parámetros requeridos para cada operación.

Ésto brinda un nivel de libertad adicional a desarrolladores a la de desarrollar un cliente para los servicios de Libertya en función de la tecnología que éste se encuentre utilizando.

Desde un cliente, la URL de conexión al Web Service es la siguiente:

• http://SERVIDOR_LIBERTYA:PUERTO_LIBERTYA/axis/services/LibertyaWSE