Guida che illustra come realizzare un client SOAP per i Web Services di SugarCRM utilizzando il framework Apache CXF.

1. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
SugarCRM
Web
Services:
Build
a
Apache
CXF
Client
SugarCRM[1]
espone
all’esterno
il
core
delle
proprie
funzionalità
pubblicandole
come
Web
Services,
quindi
niente
di
più
semplice
che
creare
un
client
Java,
C#,
C++,
PHP
e
chi
più
ne
ha
più
ne
metta
per
interagire
con
essi;
non
sempre
però
la
questione
è
così
semplice
!!!
Chi
lavora
pesantemente
con
la
tecnologia
dei
Web
Services
è
cosciente
del
fatto
che
gli
standard
esistenti
lasciano
un
notevole
grado
di
libertà
tale
per
cui
possono
essere
interpretati
diversamente
dalle
varie
case
produttrici
di
software,
con
la
conseguenza
di
non
garantire
in
alcuni
casi
l’interoperabilità.
Potrebbe
cioè
essere
impossibile,
ad
esempio,
accedere
ad
un
web
service
creato
con
Axis
(Java)
utilizzando
.NET
(Microsoft).
E’
stato
creato
un
comitato
denominato
WS-­‐I
(Web
Services
Interoperability)
con
l’obiettivo
di
risolvere
i
problemi
legati
all’interoperabilità.
SugarCRM
dichiara
di
essere
compliant
WS-­‐I
1.0
Basic
Profile[2]
,
ciò
significa
che
dovremmo
essere
in
grado
d’interagire
con
i
servizi
web
di
SugarCRM
attraverso
client
generati
(a
partire
dal
documento
WSDL)
con
Apache
Axis,
JAX-­‐WS,
Apache
CXF,
etc…
Prima
di
andar
sul
pratico,
desidero
fare
un
breve
refresh
su
style
binding
e
use.
Il
documento
WSDL[3]
descrive
il
servizio
web,
in
particolare,
l’elemento
binding
costituisce
la
specifica
concreta
di
protocollo
(in
particolare
il
protocollo
SOAP)
e
formato
dati,
relativo
a
un
elemento
portType.
Il
SOAP
binding,
che
definisce
il
modello
di
messaging,
che
può
essere:
• Remote
Procedure
Call
(RPC)
Style;
• Document
Style.
La
regola
di
codifica
dei
dati
specificata
dall’attributo
use,
può
essere,
encoded
o
literal.
Sintetizzando,
esistono
quattro
diverse
combinazioni
di
stile
e
codifica,
sulle
quali
entrambe
le
parti
coinvolte
devono
convenire
prima
d’iniziare
lo
scambio
d’informazioni:
per
esempio,
un
server
che
supporta
soltanto
la
codifica
letterale
per
lo
scambio
dei
documenti
non
sarà
mai
in
grado
di
comunicare
con
un
client
che
utilizza
il
modello
RPC
con
la
codifica
encoded.
L’elenco
a
seguire
mostra
un
riepilogo
delle
possibili
combinazioni:
• Document/Literal;
• Document/Encoded;
• RPC/Literal;
• RPC/Encoded.
17/08/12
1
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

2. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Nelle
successive
figure
ho
evidenziato
style
e
use
nelle
due
combinazioni
RPC.
L’estratto
mostrato
fa
riferimento
al
documento
WSDL
di
SugarCRM
(Community
Edition
versione
6.4).
Figura
1
WSDL
Web
Services
di
SugarCRM
RPC/Encoded
Figura
2
WSDL
Web
Services
di
SugarCRM
RPC/Literal
Dalla
documentazione
di
SugarCRM
risultano
supportate
le
due
combinazioni
RPC,
quella
di
default
è
RPC/Encoded.
Le
URL
per
accedere
al
documento
WSDL
per
le
due
combinazioni
sono:
• RPC/Encoded:
http://<hostname>:<port>/service/v2/soap.php?wsdl
• RPC/Literal:
http://<hostname>:<port>/service/v2/soap.php?wsdl&sty
le=rpc&use=literal
Build
del
Client
In
precedenti
articoli
pubblicati
su
questo
blog
sono
stati
affrontati
temi
circa
lo
sviluppo
di
client
per
i
servizi
web
di
SugarCRM,
sia
utilizzando
il
linguaggio
Java
(tramite
il
framework
Apache
Axis
1.4)
sia
utilizzando
.NET
Framework.
In
questo
caso
creeremo
il
client
utilizzando
Apache
CXF[4].
I
requisiti
minimi
per
portar
a
casa
il
risultato
sono:
• Installazione
e
Configurazione
del
framework
Apache
CXF
2.2.x
(o
2.5.x)
• Ant
1.7
• JDK
1.6
17/08/12
2
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

3. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Qualora
fosse
necessario
consiglio
di
fare
riferimento
alla
documentazione
ufficiale
di
ogni
componente
indicato
nel
precedente
elenco.
Costruiremo
il
client
a
partire
dal
documento
WSDL
di
SugarCRM,
in
particolare
faremo
riferimento
alla
versione
4
delle
API
di
SugarCRM
Community
Edition
6.4.
Nella
successiva
tabella
sono
indicate
le
versioni
delle
API
e
le
relative
versioni
di
SugarCRM.
API
Version
SugarCRM
Version
V2
5.5.0
V3
6.1.0
V3_1
6.1.0
V4
6.2
e
successive
Tabella
1.
Versioni
delle
API
L’URL
di
accesso
ai
servizi
rispetta
il
pattern
http://<hostname>:<port>/service/vX/soap.php
dove
X
indica
la
versione
delle
API
indicata
in
Tabella
1
(prima
colonna).
Per
generare
il
client
utilizzeremo
il
tool
wsdl2java
locato
in
$CXF_HOME/bin,
specificando
l’URL
del
documento
WSDL
e
una
serie
di
altri
parametri.
E’
utile
ricordare
che
Apache
CXF
supporta
la
combinazione
RPC/Literal
e
non
quella
di
default
di
SugarCRM
RPC/Encoded.
Per
questo
motivo,
l’URL
del
WSDL
da
fornire
a
Apache
CXF
è
il
seguente:
• http://<hostname>:<port>/service/v4/soap.php?wsdl&style=rpc&use=li
teral
Qualora
forniate
l’URL
non
corretta
ad
Apache
CXF
in
fase
di
generazione
del
client,
riceverete
il
seguente
errore:
WSDLToJava Error: Rpc/encoded wsdls are not supported with CXF
Il
comando
per
generare
il
client
è
il
seguente:
wsdl2java -d /Users/amusarra/SugarCRMCE64v4SOAPLibray
-client -ant -exsh false -dns true -dex true
-verbose
"http://<hostname>:<port>/service/v4/soap.php?wsdl&style=rpc&use=literal"
Il
tool
creerà
all’interno
della
directory
specificata
dal
parametro
-­‐d
tutti
i
sorgenti
Java
del
client
+
il
file
build.xml
di
Ant
che
potrete
utilizzare
per
fare
il
build
e
test
del
client.
Se
non
diversamente
specificato,
il
client
sarà
creato
utilizzando
JAX-­‐WS
come
FrontEnd
e
JAX-­‐B
come
DataBinding,
il
vantaggio
di
questa
soluzione
è
rappresentato
dal
fatto
che
sarete
in
grado
di
eseguire
il
client
senza
la
necessità
di
librerie
aggiuntive,
basta
la
sola
JDK/JRE.
17/08/12
3
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

4. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Apache
CXF,
oltre
a
creare
tutte
le
classi
Java
a
supporto,
crea
inoltre
una
classe
di
test
da
completare
oltre
che
a
poter
eseguire
la
classe
stessa
via
Ant.
Il
nome
della
classe
di
test
è:
• com.sugarcrm.sugarcrm.SugarsoapPortType_SugarsoapPort_Client.java
una
volta
che
avrete
completato
la
classe
con
qualche
prova
di
chiamata
a
uno
o
più
metodi
esposti
dal
servizio,
potrete
verificare
il
risultato
eseguendo
il
comando:
ant SugarsoapPortTypeClient
ottenendo
(come
nel
mio
caso)
un
risultato
del
genere:
SugarsoapPortTypeClient:
[java] SugarCRM Server Info...
[java] Version 6.4.0
[java] Flavor CE [java] Invoking login...
[java] Login Successfully for admin
[java] Your session Id: 98b439d68141cf38fe2441382fb6513b
[java] Invoking getUserId...
[java] Your UserId is: 1
[java] Invoking logout...
BUILD SUCCESSFUL Total time: 3 seconds
Ho
completato
la
classe
test
in
modo
da
eseguire
le
operazioni
di
ServerInfo,
Login,
GetUserId
e
Logout.
A
questo
punto
il
gioco
è
fatto.
Consiglio
di
realizzare
un
bel
jar
del
client
appena
creato
per
utilizzarlo
ovunque
sia
necessario
accedere
ai
dati
del
CRM
di
Sugar.
Risorse
Quanto
realizzato
per
la
stesura
di
quest’articolo
è
stato
pubblicato
sul
Repository
GitHub
raggiungibile
all’indirizzo:
https://github.com/amusarra/SugarCRMCE64v4SOAPLibrary
Il
repository
contiene:
• Il
progetto
Eclipse
chiamato
SugarCRMCE64v4SOAPLibray
• Il
documento
WSDL
(RPC/Literal)
del
servizio
(in
resources/wsdl)
• Il
documento
XSD
del
servizio
(in
resources/xsd)
• Il
Jar
SugarCRMCE64v4SOAPLibrary.jar
del
client
(in
build)
17/08/12
4
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

5. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Riferimenti
David
A.
Chappell,
T.
J.
(2002).
Java
Web
Services.
O’REILLY.
Antonio
Musarra.
(4
Aprile
2011).
Costruire
un
client
Java
per
SugarCRM
Antonio
Musarra.
(15
Novembre
2011).
Building
a
Client
.NET
for
SugarCRM
[1]
SugarCRM
Web
Service
Overview
[2]
Chris
Ferris.
(1
Ottobre
2002).
First
look
at
the
WS-­‐I
Basic
Profile
1.0
[3]
Russell
Butek.
(31
Ottobre
2003).
Which
style
of
WSDL
should
I
use?
[4]
The
Apache
Software
Foundation.
Apache
CXF:
An
Open-­‐Source
Services
Framework
17/08/12
5
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike