LYWS: Generalidades

1

= Libertya Web Services {{id name="libertya-web-services" /}}=

2

3

== Generalidades, instalación y uso {{id name="generalidades-instalación-y-uso" /}}==

4

5

= Indice {{id name="indice" /}}=

= Objetivos de este documento {{id name="objetivos-de-este-documento" /}}=

10

11

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.

12

13

= Prerequisitos {{id name="prerequisitos" /}}=

14

15

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.

16

17

= Instalación del servicio {{id name="instalación-del-servicio" /}}=

18

19

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:

20

21

*. **OXP_HOME/jboss/server/openXpertya/deploy/**

22

23

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**:

24

25

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

26

27

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

28

29

= Acceso al Servicio {{id name="acceso-al-servicio" /}}=

30

31

Accediendo desde el navegador a:

32

33

*. **http:~/~/SERVIDOR_LIBERTYA:PUERTO_LIBERTYA/axis/servlet/AxisServlet**

34

35

(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.

36

37

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

38

39

*. **http:~/~/SERVIDOR_LIBERTYA:PUERTO_LIBERTYA/axis/services/LibertyaWS**

40

41

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:

42

43

~/~/ 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(…);

44

45

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.

46

47

= Mecanismo de Interacción {{id name="mecanismo-de-interacción" /}}=

48

49

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**.

50

51

== ParameterBean y Result Bean {{id name="parameterbean-y-result-bean" /}}==

52

53

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

54

55

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).

56

57

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.

58

59

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

60

61

== Jerarquía de clases {{id name="jerarquía-de-clases" /}}==

62

63

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

*. Object\\

*. ParameterBean

**. BPartnerParameterBean\\

68

**. DocumentParameterBean

69

***. InvoiceParameterBean\\

70

*. ResultBean

71

**. BPartnerResultBean\\

72

**. DocumentResultBean\\

73

**. MultipleDocumentsResultBean

74

75

**//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.):

76

77

/~*~* 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>();

78

79

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.

80

81

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.

82

83

/~*~*\\* 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) { … }

84

85

/~*~*\\* 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) { … }

86

87

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

88

89

/~*~* 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>();

90

91

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.

92

93

/~*~* 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>();

94

95

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).

96

97

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.

98

99

== Log de Ejecución {{id name="log-de-ejecución" /}}==

100

101

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

102

103

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

104

105

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

110

111

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.

112

113

== Parámetros y Argumentos de la invocación {{id name="parámetros-y-argumentos-de-la-invocación" /}}==

114

115

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.

116

117

Un ejemplo se muestra a continuación:

118

119

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;

120

121

= LibertyaWSE {{id name="libertyawse" /}}=

122

123

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.

124

125

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.

126

127

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.

128

129

É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.

130

131

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

132

133

*. **http:~/~/SERVIDOR_LIBERTYA:PUERTO_LIBERTYA/axis/services/LibertyaWSE**

Wiki source code of LYWS: Generalidades

Navigation