Libertya Web Service

ndice de contenido
Objetivos de este documento................................................................................................2
Prerequisitos..........................................................................................................................3
Instalacin del servicio...........................................................................................................3
Acceso al Servicio..................................................................................................................3
Mecanismo de Interaccin.....................................................................................................3
ParameterBean y Result Bean..........................................................................................
!erarqu"a de clases.......................................................................................................
#o$ de %jecucin....................................................................................................................&
Par'metros y Ar$umentos de la invocacin..................................................................(
API..........................................................................................................................................)
#ibertya*S% .........................................................................................................................)
Objetivos de este documento
%l +resente documento e,+lica la -orma de acceder al Servicio *eb #ibertya y brinda el
detalle de los m.todos y +ar'metros requeridos en cada caso.
Adem's +resenta ejem+los de uso y -uncionalidades adicionales como es la $eneracin
del arc/ivo de log de invocaciones y errores.
Prerequisitos
#0*S versin 2123 requiere al menos la versin 4.52 de #ibertya 3OR%. 6e todas
maneras7 es +robable que sea +arcialmente com+atible con versiones anteriores de
#ibertya.
Instalacin del servicio
6escom+rimir el 8IP con nombre org.libertya.ws.r28GC.i! dentro del directorio9
"O#P$%O&'"jboss"server"o!en#!ertya"de!loy"
6onde O#P$%O&' re-iere al directorio rai: de #ibertya ;$eneralmente llamado
(ervidorO#P<. 3omo resultado7 dentro del directorio de!loy se deber"a /aber creado el
directorio a)is.war9
"O#P$%O&'"jboss"server"o!en#!ertya"de!loy"a)is.war
Recordar que +ara estas acciones es necesario contar con los corres+ondientes +ermisos
de escritura sobre el directorio en cuestin.
*cceso al (ervicio
Accediendo desde el nave$ador a9
http://IP_NOMBRE_SERVIDOR_LIBERTYA/axis/servlet/AxisServlet
se +ueden observar los servicios actualmente im+lementados.
6esde un cliente !ava7 la =R# de cone,in al *eb Service es la si$uiente9
http://IP_NOMBRE_SERVIDOR_LIBERTYA/axis/services/LibertyaWS
%l acceso a los servicios desde !ava es sencillo debido a las clases de so+orte +ara el
cliente que se entre$an +ara este -in. Su+oniendo que el Servidor de A+licaciones de
#ibertya se encuentra en 192.168.0.10:8080, el cdi$o +ara el acceso al *S de #ibertya
es9
// Conexin al WS
LibertyaWSServiceLocator locator = new LibertyaWSServiceLocator();
locator.setLibertyaWSEndpointAddress(http://192.168.0.10:8080/axis/services/LibertyaWS);
// Recuperacin del Servicio
ws.libertya.org.LibertyaWS lyws = locator.getLibertyaWS();
// Invocacin de ejempo a eliminacin de factura
ResultBean result = lyws.invoiceDeleteByID(...);
>O?A. #as clases #ibertya*SService#ocator7 #ibertya*S y las restantes clases
necesarias +ara el acceso y uso del *S de #ibertya son +ro+orcionadas junto con la
+resente documentacin. Mas adelante se +resenta el ejem+lo com+leto de a+licacin
3liente del *S de #ibertya7 incluyendo los arc/ivos -uente de !ava.
&ecanismo de Interaccin
%n la interaccin con el *S +or +arte del cliente se invoca a uno de los servicios en
cuestin7 +as'ndole los +ar'metros corres+ondientes7 los cuales se encuentran
enca+sulados en una jerarqu"a de clases de +ar'metros cuya su+erclase es
ParameterBean. #ue$o de +rocesar7 el *S devolver' la res+uesta con el mismo criterio7
en este caso la su+erclase de ResultBean.
ParameterBean y Result Bean
3ada invocacin a un servicio requiere la car$a +revia de un conjunto de datos necesarios
+ara la ejecucin de los servicios.
#os datos a car$ar var"an de+endiendo la o+eracin7 aunque /ay una serie de datos
obli$atoria en todos los casos7 que son9 >ombre de usuario7 3ontrase@a7 3om+a@"a7
Or$ani:acin ;la cual +uede ser 5<.
#as subclases de ParameterBean contienen in-ormacin adicional es+ec"-ica. Por
ejem+lo9 BPartnerParameterBean contendr' in-ormacin de la direccin de la %ntidad
3omercial7 e InvoiceParameterBean contendr' in-ormacin sobre las l"neas de una
-actura.
6e manera an'lo$a7 se obtendr' una clase ResultBean ;o al$una de sus subclases< con
los resultados de la o+eracin.
Jerarqua de clases
#a jerarqu"a actual de +ar'metros y resultados es la si$uiente9
Object
|
+--ParameterBean
| |
| +--BPartnerParameterBean
| |
| +--DocumentParameterBean
| |
| +--InvoiceParameterBean
|
+--ResultBean
|
+--BPartnerResultBean
|
+--DocumentResultBean
|
+--MultipleDocumentsResultBean
ParameterBean contiene los miembros $enerales a +asar como +ar'metro7 tal como
com+a@"a7 usuario7 +assAord7 y los datos a car$ar +ara la tabla +rinci+al ;.sta
de+endiendo el *S en el que estemos9 si es el *S de %ntidades 3omerciales ser' la
tabla C_BPartner7 si es de -acturas ser' la tabla C_Invoice7 etc.<9
/** Usuario LY */
protected String userName = "";
/** Contrasea LY */
protected String password = "";
/** Compaa a acceder */
protected int clientID = 0;
/** Organizacin */
protected int orgID = 0;
/** Coeccion para a ta!a principa */
protected "as#$ap%String& String' mainTable = ne( "as#$ap%String& String')*;
#os datos a car$ar en la tabla en cuestin se reciben como +ares9 Bnombre de columna7
datoC. 6e esta manera no es necesario modi-icar el *S en caso de que +osteriormente
se modi-ique el nDmero de columnas de una tabla7 sim+lemente se env"a un +ar adicional
desde el cliente.
#as subclases am+l"an esta estructura con in-ormacin adicional se$Dn corres+onda. Por
ejem+lo +ara %ntidades 3omerciales7 es necesario contar con in-ormacin relacionada a
su direccin. #as -acturasE+edidosEremitos tendr'n las l"neas7 etc. 3ada subclase
+resenta m.todos +ara /acer m's intuitiva la car$a de +ar'metros desde el cliente7 con
invocaciones inde+endientes +ara cada tabla9
/**
* +ncorpora una nue,a coumna a os datos de par-metro a ./C/
* 0param coumn1ame nom!re de a coumna
* 0param coumn2aue ,aor de a coumna
*/
pu!ic ,oid addCoumn3o45artner)String coumn1ame& String coumn2aue* 6
///
7
/**
* +ncorpora una nue,a coumna a os datos de par-metro de direccin de a ./C/
* 0param coumn1ame nom!re de a coumna
* 0param coumn2aue ,aor de a coumna
*/
pu!ic ,oid addCoumn3oLocation)String coumn1ame& String coumn2aue* 6
///
7
#a jerarqu"a de resultados es similar. #a su+erclase ResultBean contiene los miembros9
/** . resutado 8ue un error */
protected !ooean error = 8ase;
/** $ensa9e de error */
protected String error$sg = "";
/** 2aores de retorno principaes o de ta!a principa */
protected "as#$ap%String& String' main:esut = ne( "as#$ap%String& String')*;
#ue$o las subclases am+l"an la in-ormacin a devolver7 +or ejem+lo BPartnerResultBean
contiene in-ormacin in/erente a este *S se$Dn los requerimientos7 tal como direccin de
-acturacin7 usuario de contacto7 etc.
/** 2aores de retorno de a ;tima direccin de 8acturacin */
protected "as#$ap%String& String' !i<ddress = ne( "as#$ap%String& String')*;
/** +ndica si e=isten m-s direcciones */
!ooean mode<ddresses = 8ase;
/** 2aores de retorno de contacto m-s nue,o */
protected "as#$ap%String& String' userContact = ne( "as#$ap%String& String')*;
6esde el cliente se instancian entonces estas clases de +ar'metros7 se asi$nan los
valores y lue$o se invoca al servicio7 +as'ndo como +ar'metro este objeto ;adem's de
otros datos se$Dn corres+onda<. >otar que de+endiendo el servicio se recibeEdevuelve
una es+eciali:acin o una $enerali:acin en la jerarqu"a ;no en todos los casos /acemos
uso de las /ojas de la jerarqu"a<. %sto /ace m's -'cil la inter+retacin de qu. +ar'metros
se deben enviar en cada caso y qu. datos obtendremos como resultado.
+og de 'jecucin
?oda ejecucin de una accin o error queda +ersistida en el lo$ con el si$uiente -ormato9
Fec/a y Gora7 HI>FOI*SJ%RRORIMO6%#J%RRORK ;=suario< L 6atos es+ec"-icos de
cada ejecucin.
6ic/o arc/ivo de lo$ se llama lyws.lo y se escribir' en la ubicacin es+eci-icada en la
variable de entorno !"P_WS_L!#. Si dicha variable no se encuentra especificada,
utilizar por defecto la variable de entorno !"P_$!%& de la a+licacin ;comunmente
EServidorOMP en instalaciones #inu,7 y 39NServidorOMP en *indoAs<. ?ener en cuenta
que es necesario contar con los +ermisos corres+ondientes en el directorio en cuestin
+ara que el *S de #ibertya +ueda escribir el arc/ivo.
%jem+lo9
>0?>@0A@0B ?CD>0DC0 E+1FOG )<dminLi!ertHa* @ org/i!ertHa/(s/#ander/+n,oiceIocument"ander @ .9ecutando
in,oiceIeete
>0?>@0A@0B ?CD>0DC0 E$OI.LJ.::O:G )<dminLi!ertHa* @ org/i!ertHa/(s/#ander/+n,oiceIocument"ander @
org/i!ertHa/(s/e=ception/$ode.=ceptionD 1o se pudo recuperar un registro para a ta!a CJ+n,oice con os
criterios especi8icados/ )org/i!ertHa/(s/#ander/Kenera"ander/get5O)Kenera"ander/9a,aDB0A*&
org/i!ertHa/(s/#ander/+n,oiceIocument"ander/in,oiceIeete)UnLno(n Source*///
>0?>@0A@0B ?CD>0DC0 E+1FOG )<dminLi!ertHa* @ org/i!ertHa/(s/#ander/45artnerC:UI"ander @ .9ecutando
!5artnerCreate
>0?>@0A@0B ?CD>0DC? E$OI.LJ.::O:G )<dminLi!ertHa* @ org/i!ertHa/(s/#ander/45artnerC:UI"ander @
org/i!ertHa/(s/e=ception/$ode.=ceptionD .rror a persistir entidad comerciaDCoud not sa,e c#angesD D .=iste un
registro de .ntidad Comercia Mue Ha contiene e ,aor ,aue?AA para e campo Ca,e/ . ,aor de este campo no
puede ser dupicado/ )org/i!ertHa/(s/#ander/45artnerC:UI"ander/!5artnerCreate)UnLno(n Source*///
>0?>@0A@0B ?CD>0DC? E+1FOG )<dminLi!ertHa* @ org/i!ertHa/(s/#ander/45artnerC:UI"ander @ .9ecutando
!5artner:etrie,e
>0?>@0A@0B ?CD>0DC? E+1FOG )<dminLi!ertHa* @ org/i!ertHa/(s/#ander/+n,oiceIocument"ander @ .9ecutando
in,oiceCreateCustomer
%n el ejem+lo +rimeramente se est' invocando a invoice6elete7 +osteriormente se indica
un error de modelo ;no se encuentra la -actura en cuestin<7 lue$o se intenta crear una
entidad comercial mediante bPartner3reate7 y +osteriormente un error de modelo
indicando que ya e,iste una entidad comercial con la clave de bDsqueda es+eci-icada.
Por Dltimo se invoca a la recu+eracin de una entidad comercial y la creacin de una
-actura.
Par'metros y (rumentos de la invocaci)n
Adicionalmente al stacO de error in-ormativo7 se incor+ora en el lo$ el conjunto de
paretros enviados en el !araeter"ean corres+ondiente7 as" como los arguentos
adicionales que com+letan la -irma del m.todo invocadoP indicados mediante Parameters
y &et,od *rguments corres+ondientemente. =n ejem+lo se muestra a continuacin9
ERROR. java.lang.Exception: Error de acceso para usuario AdminLibertya
(org.libertya.ws.handler.eneral!andler.chec"Login(eneral!andler.java:#$$%&
org.libertya.ws.handler.eneral!andler.init(eneral!andler.java:'$%&
org.libertya.ws.handler.Allocation(ocument!andler.allocation)reateReceipt(Allocation(ocum
ent!andler.java:'*%&
org.libertya.ws.handler.Allocation(ocument!andler.allocation)reateReceipt(Allocation(ocum
ent!andler.java:+,%&
org.libertya.ws.Libertya-./mpl.allocation)reateReceipt(Libertya-./mpl.java:$0+%&
org.libertya.ws.client.Libertya-.)lient.main(Libertya-.)lient.java:$$'%%
- Parameters -
org.libertya.ws.bean.parameter.Allocation1arameter2ean 3 4ser5ame 6 AdminLibertya7
)lient/( 6 #8#88#,7 Org/( 6 #8#88*$
main9able: (escription 6 4n R) desde -.7
/nvoices:
Amount 6 $*87 ):/nvoice:/( 6 #80#,;+7
1ayments:
Amount 6 '87 ):1O.1ayment<edium:/( 6 #8#88$=7 ):/nvoice:/( 6 #80#,;*7
9rans>er5o 6 #0$+7 Amount 6 $87 ):1O.1ayment<edium:/( 6 #8#88$+7 9rans>er(ate 6 08#03
8;38$ #8:08:887 ):2an"Account:/( 6 #8#88'#7
Amount 6 087 )redit)ard5umber 6 #80;0;0=#=#87 ):1O.1ayment<edium:/( 6 #8#88$,7 A:2an"
6 )oma>i7 )oupon5umber 6 #0$+#0$+7 <:Entidad?inanciera1lan:/( 6 #8#88$$7
Amount 6 +87 ):1O.1ayment<edium:/( 6 #8#88$'7 (ate9rx 6 08#038;38$ #8:0,:#*7 (ue(ate
6 08#038;38+ #8:0,:#*7 )hec"5o 6 #0$+*7 ):2an"Account:/( 6 #8#88'87
Amount 6 +87 ):1O.1ayment<edium:/( 6 #8#88$$7 ):)ash:/( 6 #8#88,07
Amount 6 '87 ):)ashLine:/( 6 #8#8#887 ):1O.1ayment<edium:/( 6 #8#88$*7
):1ayment:/( 6 #8##;,87 Amount 6 $87 ):1O.1ayment<edium:/( 6 #8#88$*7
Amount 6 *87 ):1O.1ayment<edium:/( 6 #8#88$;7 Retenc:(ate 6 08#038;38+ #8:++:#=7
Retenc:(ocument5o 6 *$###=#7 ):Retencion.chema:/( 6 #8#88*+7
- Method arguments: b1artner/( 6 3#7 b1artner@alue 6 <)7 tax/( 6 null7 isEarly1ayment 6
>alse7
*PI
Se adjunta al +resente documento el !ava6oc corres+ondiente a la im+lementacin de los
*ebServices.
+ibertya-('
Si bien #0*S sim+li-ica considerablemente la $estin de +ar'metrosEresultados desde
!ava $racias a la jerarqu"a de "eans #!araeters $ %esults&7 el manejo desde otras
tecnolo$"as +uede lle$ar a requerir el uso de estructuras m's tradicionales.
%s +or .sto que se /a de-inido un conjunto de Ara++ers bajo #0*S% +ara el total de los
servicios de #0*S7 los cuales +resentan una $estin de ar$umentos con ti+os +rimitivos
dentro del conte,to de Servicios *eb.
#as o+eraciones incluidas en #0*S% son +or lo tanto e,actamente las mismas que +ara
#0*SP variando Dnicamente los +ar'metros requeridos +ara cada o+eracin.
Qsto brinda un nivel de libertad adicional a desarrolladores a la de desarrollar un cliente
+ara los servicios de #ibertya en -uncin de la tecnolo$"a que .ste se encuentre utili:ando.
6esde un cliente7 la =R# de cone,in al *eb Service es la si$uiente9
http://IP_NOMBRE_SERVIDOR_LIBERTYA/axis/services/LibertyaWSE