Nel corso di quest’articolo vedremo come realizzare un client Java per accedere alle informazioni registrate sul sistema di CRM, vedremo inoltre come realizzare una semplice applicazione Java che utilizzerà il client per eseguire una serie di operazioni elementari come: login, creazione di un nuovo contatto e recupero dati. Il sistema SugarCRM (SugarCRM Inc., 2004) espone all’esterno delle interfacce per l’accesso ai dati, queste interfacce supportano il protocollo SOAP e REST (SugarCRM Inc., 2010). La versione di SugarCRM cui faremo riferimento durante l’intero articolo è la 6.1 Community Edition (SugarCRM Inc., 2010).

1. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Costruire
un
client
Java
per
SugarCRM
Nel
corso
di
quest’articolo
vedremo
come
realizzare
un
client
Java
per
accedere
alle
informazioni
registrate
sul
sistema
di
CRM,
vedremo
inoltre
come
realizzare
una
semplice
applicazione
Java
che
utilizzerà
il
client
per
eseguire
una
serie
di
operazioni
elementari
come:
login,
creazione
di
un
nuovo
contatto
e
recupero
dati.
Il
sistema
SugarCRM (SugarCRM Inc., 2004)
espone
all’esterno
delle
interfacce
per
l’accesso
ai
dati,
queste
interfacce
supportano
il
protocollo
SOAP
e
REST
(SugarCRM Inc., 2010).
La
versione
di
SugarCRM
cui
faremo
riferimento
durante
l’intero
articolo
è
la
6.1
Community
Edition
(SugarCRM Inc.,
2010).
La
scelta
del
protocollo
ricade
su
SOAP,
esistono
modi
diversi
per
creare
un
client
SOAP
Java
in
grado
di
colloquiare
con
un
servizio
web,
la
via
più
semplice
è
quella
di
utilizzare
l’ormai
maturo
framework
Apache
Axis
(The Apache Software
Foundation, 2011).
Apache
Axis
è
un
framework
Open
Source
che
implementa
un
SOAP
Engine,
utile
per
creare,
pubblicare
e
consumare
Web
Service
in
Java
(ma
in
realtà
supporta
anche
C/C++).
Apache
Axis
ci
sarà
d’aiuto
per
creare
il
Service
SOAP
Stub
+
Data
Type
partendo
dal
documento
WSDL
distribuito
da
SugarCRM.
Esistono
due
versioni
di
Apache
Axis,
per
il
nostro
client
utilizzeremo
la
versione
meno
recente
(Apache
Axis1
1.4)
perché
quella
consigliata
e
che
funziona
senza
problemi
con
l’attuale
WSDL
fornito
con
SugarCRM.
I
passi
da
seguire
per
raggiungere
l’obiettivo
sono
i
seguenti:
• Generazione
Stub
Java
con
Apache
Axis;
• Compilazione
dello
Stub
Java
come
libreria
Java
(jar);
• Creazione
del
progetto
Java
SugarCRMSOAPClient.
1. Generazione
del
Client
Java
Prima
di
procedere
con
la
generazione
del
client,
occorre
completare
con
successo
i
seguenti
punti:
• Download
di
Apache
Axis
dall’indirizzo
http://ws.apache.org/axis/java/releases.html
.
Ricordo
che
la
versione
da
scaricare
è
la
1.4;
• Configurazione
del
framework
Apache
Axis.
La
configurazione
di
Apache
Axis
è
limitata
alla
registrazione
nel
proprio
ambiente
operativo
(sia
Windows
sia
Unix/Linux)
delle
seguenti
variabili
di
ambiente:
• AXIS_HOME:
Directory
d’installazione
(esempio:
/opt/axis,
c:axis)
• AXIS_LIB:
Directory
delle
librerie
(esempio:
$AXIS_HOME/lib)
• AXISCLASSPATH:
Java
class
path
(esempio:
$AXIS_LIB/axis.jar:$AXIS_LIB/commons-­‐loggins.jar)
04/04/11
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
Affinché
Apache
Axis
funzioni
correttamente,
è
necessario
verificare
l’impostazione
della
variabile
di
ambiente
JAVA_HOME,
questa
rappresenta
la
directory
d’installazione
della
vostra
Java
Virtual
Machine.
Nel
caso
di
ambienti
Unix/Linux
(e
in
modo
analogo
anche
su
ambienti
Windows)
occorre
procedere
nel
modo
seguente
per
impostare
le
variabili
di
ambiente
illustrate
in
precedenza:
$ export AXIS_HOME="/opt/axis-1_4"
$ export AXIS_LIB="$AXIS_HOME/lib"
$ export JAVA_HOME="/System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home"
$ AXISCLASSPATH=$AXIS_LIB/axis-ant.jar:$AXIS_LIB/axis.jar:$AXIS_LIB/commons-discovery-
0.2.jar:$AXIS_LIB/commons-logging-1.0.4.jar:$AXIS_LIB/jaxrpc.jar:$AXIS_LIB/log4j-
1.2.8.jar:$AXIS_LIB/saaj.jar:$AXIS_LIB/wsdl4j-1.5.1.jar:$AXIS_LIB/mail-
1.4.1.jar:$AXIS_LIB/activation.jar
$ export AXISCLASSPATH="$AXIS_HOME":"$JAVA_HOME/lib/tools.jar":"$AXISCLASSPATH":"$CLASSPATH"
Listato
1
Export
variabili
di
ambiente.
Nel
precedente
listano
sono
mostrati
i
vari
export
(i
comandi
sono
validi
su
sistemi
Unix/Linux)
delle
variabili
di
ambiente
indicate
in
precedenza.
Sul
listato
ho
evidenziato
in
rosso
l’export
della
JAVA_HOME
(non
necessario
se
già
disponibile
sul
vostro
ambiente)
e
le
due
aggiuntive
librerie
Java
necessarie
per
il
supporto
al
trasferimento
di
dati
binari.
E’
possibile
scaricare
queste
due
librerie
direttamente
dal
sito
ufficiale
(Oracle)
o
utilizzare
il
servizio
online
FindJar
(http://www.findjar.com).
• activation.jar:
Java
Beans
Activation
Framework
(http://www.oracle.com/technetwork/java/jaf11-­‐139815.html);
• mail-­‐1.4.1.jar:
Java
Mail
API
(http://www.oracle.com/technetwork/java/javamail/index.html)
1.1 Generazione
dello
Stub
Java
In
questo
paragrafo
vedremo
come
utilizzare
gli
strumenti
di
Apache
Axis
per
generare
Stub
+
Data
Type.
Partendo
dal
WSDL
di
SugarCRM,
utilizzando
lo
strumento
WSDL2Java
sarà
realizzato
il
nostro
client
che
consisterà
di:
• Stub
• Data
Type
• Locator
• Port
Type
Senza
scendere
troppo
nei
dettagli,
tutti
i
precedenti
elementi
sono
il
risultato
dell’analisi
delle
definizioni
specificate
nel
documento
WSDL,
è
necessario
quindi
avere
la
locazione
esatta
del
WSDL,
tale
posizione
può
essere
remota
(URI)
oppure
locale
(file
system).
In
questo
esempio
ipotizziamo
che
il
documento
WSDL
sia
reperibile
all’indirizzo:
http://sugarcrm-­‐fe-­‐1.local/crm-­‐
6.1/service/v2/soap.php?wsdl.
04/04/11
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
Potreste
eseguire
una
veloce
verifica
di
raggiungibilità
del
documento
WSDL
specificando
il
vostro
indirizzo
(quello
dell’istanza
SugarCRM)
su
un
qualunque
browser
internet
oppure
utilizzando
strumenti
come
curl
o
wget.
$ java -cp $AXISCLASSPATH org.apache.axis.wsdl.WSDL2Java –v -B http://sugarcrm-fe-1.local/crm-
6.1/service/v2/soap.php?wsdl
Listato
2
Esecuzione
del
tool
WSDL2Java
Il
tool
WSDL2Java
eseguito
in
modo
verboso
(vedi
Listato
2),
crea
tutti
gli
elementi
necessari
a
colloquiare
con
l’interfaccia
SOAP
di
SugarCRM.
Tutte
le
classi
generate
(partendo
dalla
directory
da
cui
è
stato
eseguito
il
tool)
sono
disponibili
all’interno
della
directory
com/sugarcrm/www/sugarcrm/.
Nel
mio
caso
la
directory
~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src
è
la
mia
working-­‐dir,
in
altre
parole,
la
directory
dalla
quale
è
stato
eseguito
il
tool
e
dove
risederanno
sorgenti
e
binari
del
client
SOAP.
Parsing XML file: http://sugarcrm-fe-1.local/crm-6.1/service/v2/soap.php?wsdl
Retrieving schema at 'http://schemas.xmlsoap.org/soap/encoding/', relative to 'http://sugarcrm-fe-
1.local/crm-6.1/service/v2/soap.php?wsdl'.
Retrieving schema at 'http://schemas.xmlsoap.org/soap/encoding/', relative to 'http://sugarcrm-fe-
1.local/crm-6.1/service/v2/soap.php?wsdl'.
{http://schemas.xmlsoap.org/soap/encoding/}Struct already exists
Generating com/sugarcrm/www/sugarcrm/Return_search_result.java
Generating com/sugarcrm/www/sugarcrm/Link_field.java
Generating com/sugarcrm/www/sugarcrm/New_return_document_revision.java
Generating com/sugarcrm/www/sugarcrm/New_return_note_attachment.java
Generating com/sugarcrm/www/sugarcrm/Link_name_to_fields_array.java
Generating com/sugarcrm/www/sugarcrm/New_note_attachment.java
Generating com/sugarcrm/www/sugarcrm/Document_revision.java
Generating com/sugarcrm/www/sugarcrm/Module_list.java
Generating com/sugarcrm/www/sugarcrm/User_auth.java
Generating com/sugarcrm/www/sugarcrm/Get_entry_result_version2.java
Generating com/sugarcrm/www/sugarcrm/Entry_value.java
Generating com/sugarcrm/www/sugarcrm/New_set_entry_result.java
Generating com/sugarcrm/www/sugarcrm/Get_entry_list_result_version2.java
Generating com/sugarcrm/www/sugarcrm/New_set_entries_result.java
Generating com/sugarcrm/www/sugarcrm/New_set_relationship_list_result.java
Generating com/sugarcrm/www/sugarcrm/New_module_fields.java
Generating com/sugarcrm/www/sugarcrm/Field.java
Generating com/sugarcrm/www/sugarcrm/Get_entries_count_result.java
Generating com/sugarcrm/www/sugarcrm/Link_name_value.java
Generating com/sugarcrm/www/sugarcrm/Name_value.java
Generating com/sugarcrm/www/sugarcrm/Get_server_info_result.java
Generating com/sugarcrm/www/sugarcrm/Sugarsoap.java
Generating com/sugarcrm/www/sugarcrm/SugarsoapLocator.java
Generating com/sugarcrm/www/sugarcrm/SugarsoapPortType.java
Generating com/sugarcrm/www/sugarcrm/SugarsoapBindingStub.java
Generating ./build.xml
Listato
3
Output
del
tool
WSDL2Java.
Al
Listato
3
è
mostrato
l’output
generato
dal
tool
WSDL2Java
che
mostra
in
modo
del
tutto
evidente
le
operazioni
che
eseguite.
Volutamente
ho
specificato
l’opzione
-­‐B
nella
riga
di
comando,
questa
opzione
è
responsabile
della
creazione
dell’Ant
Buildfile
(buld.xml),
in
seguito
utilizzato
per
compilare
il
client
e
generare
il
Jar.
04/04/11
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
Il
tool
supporta
innumerevoli
altre
scelte
di
configurazione
che
potrebbero
essere
di
supporto
in
altre
situazioni,
per
maggiori
informazioni
consiglio
di
consultare
la
documentazione
ufficiale
di
Apache
Axis.
1.2 Compilazione
del
client
SOAP
In
questo
paragrafo
vedremo
come
compilare
il
client
SOAP
utilizzando
sia
il
tool
Ant (The Apache Software Foundation, 2011)
sia
il
metodo
classico.
<?xml version=”1.0”?>
<project basedir=”.” Default=”jar”>
<property name=”src” location=”.”/>
<property name=”build.classes” location=”classes”/>
<path id=”classpath”>
<pathelement location=”/opt/axis-1_4”/>
<pathelement
location=”/System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home/lib/tools.jar”/>
<pathelement location=”/opt/axis-1_4/lib/activation.jar”/>
<pathelement location=”/opt/axis-1_4/lib/axis-ant.jar”/>
<pathelement location=”/opt/axis-1_4/lib/axis.jar”/>
<pathelement location=”/opt/axis-1_4/lib/commons-discovery-0.2.jar”/>
<pathelement location=”/opt/axis-1_4/lib/commons-logging-1.0.4.jar”/>
<pathelement location=”/opt/axis-1_4/lib/jaxrpc.jar”/>
<pathelement location=”/opt/axis-1_4/lib/log4j-1.2.8.jar”/>
<pathelement location=”/opt/axis-1_4/lib/mail-1.4.1.jar”/>
<pathelement location=”/opt/axis-1_4/lib/saaj.jar”/>
<pathelement location=”/opt/axis-1_4/lib/wsdl4j-1.5.1.jar”/>
</path>
<target name=”compile”>
<mkdir dir=”${build.classes}”/>
<javac destdir=”${build.classes}” debug=”on”>
<classpath refid=”classpath” />
<src path=”${src}”/>
</javac>
</target>
<target name=”jar” depends=”compile”>
<copy todir=”${build.classes}”>
<fileset dir=”.” Casesensitive=”yes” >
<include name=”**/*.wsdd”/>
</fileset>
</copy>
<jar jarfile=”sugarcrm-soap-client-bin-1.0.0.jar” basedir=”${build.classes}” >
<include name=”**” />
<manifest>
<section name=”org/apache/ws4j2ee”>
<attribute name=”Implementation-Title” value=”Apache Axis”/>
<attribute name=”Implementation-Vendor” value=”Apache Web Services”/>
</section>
</manifest>
</jar>
<delete dir=”${build.classes}”/>
</target>
</project>
Listato
4
Ant
Buldfile
generato
dal
tool
WSDL2Java.
Al
Listato
4
è
mostrato
il
contenuto
del
file
build.xml
generato
dal
tool
WSDL2Java,
ho
evidenziato
l’unica
modifica
apportata
al
file,
il
nome
del
jar,
da
soap.jar
a
sugarcrm-­‐soap-­‐client-­‐bin-­‐1.0.0.jar.
La
compilazione
del
client
SOAP
è
davvero
semplice,
basta
eseguire
dalla
console
il
comando
ant,
il
Listato
5
mostra
l’output
ricevuto
(per
ragioni
di
spazio
e
pulizia
è
stata
omessa
qualche
riga).
04/04/11
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
Buildfile: ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src/build.xml
compile:
[mkdir] Created dir: ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src/classes
[javac] Compiling 25 source files …
jar:
[jar] Building jar: ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src/sugarcrm-soap-client-
1.0.0.jar
[delete] Deleting directory ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src/classes
BUILD SUCCESSFUL
Listato
5
Output
del
comando
ant.
Se
sulla
vostra
macchina
non
fosse
installato
il
tool
Ant,
vedremo
come
sia
comunque
possibile
compilare
i
sorgenti
java
e
generare
la
libreria
Jar
del
nostro
client
SOAP
utilizzando
il
metodo
classico.
Nel
Listato
6
è
mostrata
la
sequenza
di
comandi
che
sono
necessari
per
ottenere
la
libreria
sugarcrm-­‐soap-­‐client-­‐bin-­‐
1.0.0.jar.
$ mkdir ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src/classes
$ javac –cp $AXISCLASSPATH –d ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src/classes
com/sugarcrm/www/sugarcrm/*.java
$ cd ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src/classes
$ jar cvf sugarcrm-soap-client-1.0.0.jar com/
Listato
6
Compilazione
sorgenti
Java
e
creazione
del
jar.
2. Creazione
del
progetto
Java
SugarCRMSOAPClient
In
questo
paragrafo
vedremo
come
creare
e
configurare
correttamente
il
progetto
Java
che
chiameremo
SugarCRMSOAPClient.
Sfruttando
la
libreria
SOAP
creata
in
precedenza,
il
nostro
obiettivo
è
scrivere
del
codice
Java
che
esegua
le
seguenti
operazioni
su
una
generica
istanza
di
SugarCRM:
• Login;
• Creazione
di
un
nuovo
contatto;
• Lettura
del
contatto
inserito
in
precedenza.
L’ambiente
IDE
utilizzato
per
la
creazione
del
nostro
progetto
Java
è
Eclipse
Helios
3.6,
è
comunque
possibile
utilizzare
l’IDE
a
voi
più
adatto.
Di
seguito
sono
illustrati
i
passi
essenziali
per
creare
e
impostare
il
progetto
Java.
Figura
1
Step
1
–
Creazione
di
un
nuovo
progetto
Java.
04/04/11
5
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

6. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Figura
2
Step
2
–
Configurazione
iniziale
progetto
Java.
A
meno
di
esigenze
particolari,
consiglio
di
lasciare
le
impostazioni
predefinite
per
la
creazione
del
nuovo
progetto
Java.
04/04/11
6
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

7. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Figura
3
Step
3
–
Configurazione
Java
building.
Questa
parte
di
creazione
del
progetto
prevede
la
configurazione
dei
path
per
i
sorgenti,
binari
e
librerie
addizionali.
Per
quanto
riguarda
la
configurazione
mostrata
in
Figura
3
è
consigliabile
lasciarla
inalterata,
occorre
invece
configurare
le
dipendenze
del
progetto,
ovvero,
le
librerie.
Le
dipendenze
che
devono
essere
aggiunte
al
progetto
sono:
• Tutti
i
file
jar
di
Apache
Axis,
per
intenderci
quelli
presenti
in
$ANT_LIB;
• La
libreria
che
implementa
il
Client
SOAP
SugarCRM,
quella
che
abbiamo
creato
in
precedenza
(sugarcrm-­‐soap-­‐client-­‐bin-­‐1.0.0.jar).
Per
aggiungere
le
dipendenze
basta
semplicemente
cliccare
sulla
sezione
“Libraries”
della
finestra
illustrata
in
Figura
3.
In
Figura
4
è
invece
illustrata
la
finestra
con
la
lista
delle
dipendenze
appena
importate.
04/04/11
7
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

8. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Figura
4
Step
4
-­‐
Import
della
libreria
SugarCRM
SOAP
Client
+
Axis.
Terminata
l’importazione
delle
dipendenze,
cliccando
sul
pulsante
OK,
sarà
portata
a
termine
la
creazione
del
progetto.
Dopo
la
creazione
del
progetto
SugarCRMSOAPClient
è
possibile
visionare
l’intera
struttura
del
progetto
tramite
il
Package
Explorer,
in
Figura
5
è
illustrata
l’espansione
del
Package
com.sugarcrm.www.sugarcrm,
in
altre
parole,
la
libreria
SOAP
che
utilizzeremo
per
la
connessione
a
SugarCRM.
Figura
5
Package
Explorer
dopo
la
creazione
del
progetto.
04/04/11
8
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

9. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
2.1 Scrittura
del
codice
del
Client
A
questo
punto
siamo
finalmente
pronti
a
scrivere
il
codice
Java
che
utilizzerà
il
client
SOAP
(realizzato
in
precedenza)
per
eseguire
le
azioni
indicate
nel
precedente
paragrafo.
I
passi
da
seguire
per
portare
a
termine
l’obiettivo
sono:
• Creazione
della
classe
SugarCRMSOAPClient
(con
il
metodo
statico
main);
• Impostazione
di
una
serie
di
costanti
di
configurazione;
• Creazione
End
Point
URL
e
Service;
• Creazione
dello
Stub
Java;
• Esecuzione
della
Login
su
SugarCRM;
• Creazione
di
un
nuovo
Contatto
su
SugarCRM;
• Lettura
dei
dati
del
Contatto
appena
inserito
su
SugarCRM;
• Logout
da
SugarCRM.
Al
Listato
7
le
dichiarazioni
di
alcune
costanti
che
saranno
poi
utilizzate
in
seguito.
E’
necessario
però
sostituire
i
valori
delle
costanti
END_POINT_URL,
USER_NAME
e
USER_PASSWORD
con
i
vostri
(della
vostra
installazione
di
SugarCRM).
public class SugarCRMSoapClient {
private static final String END_POINT_URL = "http://crm-6.1/service/v2/soap.php?wsdl";
private static final String USER_NAME = "will";
private static final String USER_PASSWORD = "will";
private static final String APPLICATION_NAME = Class.class.getName();
private static final Integer TIMEOUT = 6000;
public static void main(String[] args) throws Exception {
….
}
}
Listato
7
Dichiarazione
delle
costanti.
// Create a URL end point for the client
URL wsdlUrl = null;
if (END_POINT_URL.isEmpty()) {
wsdlUrl = new URL(new SugarsoapLocator().getsugarsoapPortAddress() + "?wsdl");
} else {
wsdlUrl = new URL(END_POINT_URL);
}
System.out.println("URL endpoint created successfully!");
// Create Service for test configuration
ServiceFactory serviceFactory = ServiceFactory.newInstance();
Service service = serviceFactory.createService(wsdlUrl, new SugarsoapLocator().getServiceName());
System.out.println("Service created successfully");
Listato
8
Configurazione
URL
dell’end
point
e
Service
SugarSOAP.
04/04/11
9
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

10. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Le
operazioni
indicate
nel
Listato
8
potrebbero
lanciare
delle
eccezioni,
questa
sezione
di
codice
dovrebbe
essere
racchiusa
all’interno
di
un
blocco
try…catch,
per
ragioni
spazio
è
stato
omesso.
Le
eccezioni
che
potrebbero
essere
lanciate
sono:
MalformedURLException
e
ServiceException.
// Trying to create a stub
SugarsoapBindingStub binding = new SugarsoapBindingStub(wsdlUrl, service);
binding.setTimeout(TIMEOUT);
System.out.println("Stub created successfully!");
Listato
9
Creazione
dello
Stub.
Al
Listato
9
la
creazione
dello
stub.
Il
costruttore
dell’oggetto
ha
bisogno
dell’end
point
del
servizio
e
dell’oggetto
service
(javax.xml.rpc.Service)
creato
in
precedenza.
Lo
stub
comprende
tutte
le
operazioni
per
interagire
con
il
servizio
web
di
SugarCRM.
Anche
questa
sezione
di
codice
dovrebbe
essere
racchiusa
all’interno
di
un
blocco
try…catch,
la
creazione
dell’oggetto
stub
e
la
chiamata
di
operazioni
dello
stub,
potrebbero
lanciare
l’eccezione
di
tipo
AxisFault.
/**
* Try to login on SugarCRM
*
* 1) Prepare a MD5 hash password
* 2) Prepare a User Auth object
* 3) Execute login
*/
// 1. Prepare a MD5 hash password
MessageDigest messageDiget = MessageDigest.getInstance("MD5");
messageDiget.update(USER_PASSWORD.getBytes());
// 2. Prepare a User Auth object
User_auth userAuthInfo = new User_auth();
userAuthInfo.setUser_name(USER_NAME);
userAuthInfo.setPassword((new BigInteger(1, messageDiget.digest())).toString(16));
try {
// 3. Execute login
Entry_value loginResult = binding.login(userAuthInfo, APPLICATION_NAME, null);
System.out.println("Login Successfully for " + USER_NAME);
System.out.println("Your session Id: " + loginResult.getId());
sessionID = loginResult.getId();
} catch (RemoteException ex) {
System.out.println("Login failed. Message: " + ex.getMessage());
ex.printStackTrace();
}
Listato
10
Esecuzione
del
processo
di
login
su
SugarCRM.
A
questo
punto
è
tutto
pronto
per
eseguire
il
login
su
SugarCRM.
L’operazione
di
login
richiede
tre
parametri,
ma
dei
tre
è
fondamentale
solo
il
primo,
trascuriamo
quindi
gli
ultimi
due.
Il
primo
parametro
che
deve
essere
preparato
è
l’oggetto
User_auth
che
contiene
il
nome
utente
e
la
password,
ricordo
che
quest’ultima
deve
essere
l’hash
MD5.
L’operazione
di
login
restituisce
l’identificativo
della
sessione
utente,
questo
valore
sarà
utilizzato
in
seguito
per
le
rimanenti
operazioni.
04/04/11
10
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

11. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
/**
* Create a new Contact
*
* 1) Setting a new entry
* 2) Setting up parameters for set_entry call
* 3) Creating a name value list array from a hash map. This is not necessary
* just more elegant way to initialize and add name values to an array
*/
HashMap<String, String> nameValueMap = new HashMap<String, String>();
nameValueMap.put("first_name", "Antonio");
nameValueMap.put("last_name", "Musarra");
nameValueMap.put("title", "IT Senior Consultant");
nameValueMap.put("description","Contatto creato dal Client SOAP Java");
nameValueMap.put("email1", "antonio.musarra@gmail.com");
// Creating a new Name_value array and adding each map entry as 'name' and 'value'
Name_value nameValueListSetEntry[] = new Name_value[nameValueMap.size()];
int i = 0;
for (Entry<String, String> entry : nameValueMap.entrySet()) {
Name_value nameValue = new Name_value();
nameValue.setName(entry.getKey());
nameValue.setValue(entry.getValue());
nameValueListSetEntry[i] = nameValue;
i++;
}
// Trying to set a new entry
New_set_entry_result setEntryResponse = null;
try {
setEntryResponse = binding.set_entry(sessionID, "Contacts", nameValueListSetEntry);
} catch (RemoteException e) {
System.out.println("Set entry failed. Message: " + e.getMessage());
e.printStackTrace();
}
System.out.println("Set entry was successful! Contacts Id: " + setEntryResponse.getId());
Listato
11
Creazione
di
un
nuovo
contatto.
Una
volta
che
il
login
è
avvenuto
con
successo,
procediamo
con
la
creazione
di
un
nuovo
contatto.
L’operazione
set_entry
permette
l’inserimento
di
un
nuovo
record
su
SugarCRM,
questo,
opera
prendendo
in
input
la
sessione
dell’utente,
il
nome
del
modulo
(in
questo
caso
Contacts)
e
un
array
di
oggetti
di
tipo
Name_value
che
definiscono
nomi
e
valori
per
il
contatto
da
creare
(vedi
Listato
11).
L’operazione
set_entry
restituisce
l’identificativo
dello
SugarBean
appena
inserito,
questo
valore
sarà
utilizzato
per
il
recupero
dei
dati
del
contatto
utilizzando
l’operazione
get_entry.
L’operazione
get_entry
richiede
in
input
la
sessione
dell’utente,
il
nome
del
modulo
(in
questo
caso
Contacts),
l’identificativo
dello
SugarBean,
un
array
con
i
campi
che
desideriamo
avere
restituiti
e
infine
un
array
per
collegare
i
campi
restituiti
a
nomi
specifici
(opzionale).
L’operazione
restituisce
un
entry_list
che
contiene
un
array
di
oggetti
Name_value
contenente
le
informazioni
del
contatto.
Il
Listato
12
mostra
il
codice
responsabile
del
recupero
delle
informazioni
del
contatto
inserito
dalla
precedente
operazione
set_entry.
04/04/11
11
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

12. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
/**
* Getting an Contacts Entry (the one we just set)
*/
Link_name_to_fields_array[] link_name_to_fields_array = null;
String[] select_fields = null;
Get_entry_result_version2 getEntryResponse = null;
// Trying to get entry
try {
getEntryResponse = binding.get_entry(sessionID,"Contacts", setEntryResponse.getId(),
select_fields , link_name_to_fields_array);
} catch (RemoteException e) {
System.out.println("Get entry failed. Message: " + e.getMessage());
e.printStackTrace();
}
System.out.println("Get entry was successful! Response: ");
// Getting the fields for entry we got.
Entry_value[] entryList = getEntryResponse.getEntry_list();
for (int k=0; k < entryList.length; k++){
Entry_value entry = entryList[k];
Name_value[] entryNameValueList = entry.getName_value_list();
for (int j=0; j< entryNameValueList.length; j++){
Name_value entryNameValue = entryNameValueList[j];
//Outputting only non empty fields
if (!entryNameValue.getValue().isEmpty()){
System.out.println("Attribute Name: '" + entryNameValue.getName() + "'
Attribute Value: '" + entryNameValue.getValue() + "'");
}
}
}
Listato
12
Recupero
dei
dati
del
Contatto
inserito
su
SugarCRM.
/**
* Logout
*/
try {
binding.logout(sessionID);
System.out.println("Logout Successfully for " + USER_NAME);
sessionID = null;
} catch (RemoteException ex) {
System.out.println("Login failed. Message: " + ex.getMessage());
ex.printStackTrace();
}
Listato
13
Operazione
di
logout
da
SugarCRM.
Dopo
aver
eseguito
con
successo
tutte
le
operazioni,
è
comunque
consigliabile
ma
non
obbligatorio
eseguire
l’azione
di
logout
da
SugarCRM,
così
come
mostrato
nel
Listato
13.
Nei
due
listati
a
seguire
(Listato
14
e
Listato
15)
sono
mostrati
gli
output
generati
a
fronte
dell’esecuzione
dell’applicazione
Java
appena
realizzata.
Il
primo
listato
(vedi
Listato
14)
indica
un
problema
nella
creazione
del
servizio
a
causa
di
un
problema
di
raggiungibilità
del
documento
WSDL
di
SugarCRM.
04/04/11
12
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

13. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Il
secondo
listato
(vedi
Listato
15),
mostra
invece
la
situazione
attesa:
login,
creazione
nuovo
contatto,
recupero
dati
del
contatto
appena
creato
e
logout.
In
Figura
6
è
illustrata
la
scheda
del
contatto
(vista
da
SugarCRM)
creato
dall’applicazione
Java
attraverso
il
client
SOAP.
URL endpoint created successfully!
Service creation failed. Message: Error processing WSDL document:
java.io.IOException: WSDL2Java emitter timed out (this often means the WSDL at the specified URL
is inaccessible)!
javax.xml.rpc.ServiceException: Error processing WSDL document:
java.io.IOException: WSDL2Java emitter timed out (this often means the WSDL at the specified URL
is inaccessible)!
at org.apache.axis.client.Service.initService(Service.java:250)
at org.apache.axis.client.Service.<init>(Service.java:165)
at org.apache.axis.client.ServiceFactory.createService(ServiceFactory.java:198)
at it.lab.shirus.sugarcrm.client.soap.SugarCRMSoapClient.main(SugarCRMSoapClient.java:65)
Listato
14
Errore
nella
creazione
del
servizio.
URL endpoint created successfully!
{http://schemas.xmlsoap.org/soap/encoding/}Struct already exists
Service created successfully
Service Name:{http://www.sugarcrm.com/sugarcrm}sugarsoap
Service WSDL:http://sugarcrm-fe-1.local/crm-6.1/service/v2/soap.php?wsdl
Stub created successfully!
Login Successfully for will
Your session Id: a8e97vgnvfhrtcq3hb5midmp32
Set entry was successful! Contacts Id: 69ff87e9-758d-30f5-0acd-4d2e3fa5b513
Get entry was successful! Response:
Attribute Name: 'modified_by_name' Attribute Value: 'Will Westin'
Attribute Name: 'created_by_name' Attribute Value: 'Will Westin'
Attribute Name: 'id' Attribute Value: '69ff87e9-758d-30f5-0acd-4d2e3fa5b513'
Attribute Name: 'date_entered' Attribute Value: '2011-01-12 23:55:29'
Attribute Name: 'date_modified' Attribute Value: '2011-01-12 23:55:29'
Attribute Name: 'modified_user_id' Attribute Value: 'seed_will_id'
Attribute Name: 'created_by' Attribute Value: 'seed_will_id'
Attribute Name: 'description' Attribute Value: 'Contatto creato dal Client SOAP Java'
Attribute Name: 'deleted' Attribute Value: '0'
Attribute Name: 'first_name' Attribute Value: 'Antonio'
Attribute Name: 'last_name' Attribute Value: 'Musarra'
Attribute Name: 'title' Attribute Value: 'IT Senior Consultant'
Attribute Name: 'do_not_call' Attribute Value: '0'
Attribute Name: 'email1' Attribute Value: 'antonio.musarra@gmail.com'
Logout Successfully for will
Listato
15
Esecuzione
del
Client
SugarCRMSOAPClient.
04/04/11
13
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

14. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Figura
6
Vista
del
contatto
creato
con
il
client
SOAP.
La
consultazione
della
documentazione
delle
API
esposte
da
SugarCRM
come
servizi
web
può
aiutarvi
a
comprendere
meglio
gli
esempi
di
codice
Java
visti
fino
a
questo
momento.
Sono
sicuro
che
illustrare
lo
schema
di
parte
del
Data
Model
(XSD)
esposto
dall’interfaccia
di
SugarCRM
vi
aiuterà
a
comprendere
meglio
gli
esempi
appena
mostrati.
Figura
7
Modello
della
classe
User_auth.
Figura
8
Modello
della
classe
Entry_value.
04/04/11
14
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

15. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Figura
9
Modello
della
classe
Name_Value_List.
Figura
10
Modello
della
classe
Name_Value.
Figura
11
Modello
della
classe
New_Set_Entry_List.
Figura
12
Modello
della
class
Get_Entry_List_Result_Version2.
04/04/11
15
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

16. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Figura
13
Modello
della
classe
Entry_List.
La
documentazione
in
questo
momento
disponibile
di
SugarCRM
riguardo
al
Data
Model
esposto
dall’interfaccia
non
è
molta
chiara
o
meglio
del
tutto
assente.
Dato
che
ritengo
utile
avere
la
documentazione
di
alto
livello
del
Data
Model,
ho
estratto
dal
documento
WSDL
lo
schema
XSD
e
reso
disponibile
sul
mio
blog
all’indirizzo:
http://musarra.files.wordpress.com/2011/04/sugacrm-­‐6-­‐1ce-­‐xsd.pdf
Ho
ritenuto
opportuno
creare
un
repository
pubblico
(GitHub Inc., 2011)
contenente
quanto
prodotto
durante
la
stesura
di
questo
articolo.
Il
repository
è
raggiungibile
all’indirizzo:
https://github.com/amusarra/SugarCRMJavaSOAPClient
e
contiene
quanto
segue:
• JavaApplication:
Contiene
il
progetto
Eclipse
Java
della
nostra
applicazione
che
colloquia
con
SugarCRM
utilizzando
il
client
SOAP;
• SOAPClient:
Contiene
(sorgenti
e
binari)
della
client
SOAP
generato
con
il
framework
Apache
Axis;
• SugaCRM-­‐6.1CE-­‐WSDL.wsdl:
Documento
WSDL
della
versione
6.1
Community
Edition
di
SugarCRM;
• SugaCRM-­‐6.1CE-­‐XSD.xsd:
Documento
XSD
estratto
dal
documento
WSDL
di
SugarCRM;
• SugaCRM-­‐6.1CE-­‐XSD.pdf:
Documentazione
del
data
model
utilizzato
dall’interfaccia
esposta
da
SugarCRM.
Figura
14
Vista
web
del
repository
(git)
SugarCRMJavaSOAPClient.
04/04/11
16
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

17. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
3. Conclusioni
In
quest’articolo
ho
cercato
di
fare
“un
po’
di
luce”
su
come
impostare
e
scrivere
un
client
SOAP
Java
basato
sul
framework
Apache
Axis.
Qualcuno
di
voi
più
attento,
avrà
notato
il
disaccoppiamento
che
ho
mantenuto
tra
il
client
SOAP
Java
e
l’applicazione
Java
che
nelle
sue
logiche
di
business
utilizza
il
client
per
interagire
con
SugarCRM:
questa
è
una
best
practice.
L’ausilio
di
alcuni
esempi
base
di
codice
(login,
set_entry
e
get_entry),
ha
dimostrato
come
possa
essere
semplice
interagire
con
i
servizi
web
esposti
da
SugarCRM,
rendendo
più
facile
per
chi
è
interessato
la
costruzione
di
un
client
Java
per
i
servizi
web
di
SugarCRM.
Sono
ben
accetti
i
vostri
commenti
per
ogni
genere
questione
in
merito
al
tema
trattato.
I
commenti
possono
essere
lasciati
all’indirizzo:
http://musarra.wordpress.com/2011/04/04/costruire-­‐un-­‐client-­‐java-­‐per-­‐
sugarcrm
Bibliography
GitHub
Inc.
(2011).
Git
Reference.
Tratto
da
GitHub
Social
Coding:
http://gitref.org/
SugarCRM
Inc.
(2010).
Sugar
Community
Edition
Documentation.
Tratto
da
Sugar
Community
Edition
Documentation
|
SugarCRM
-­‐
Commercial
Open
Source
CRM:
http://www.sugarcrm.com/crm/support/documentation/SugarCommunityEdit
ion
SugarCRM
Inc.
(2010).
Sugar
Community
Edition
Documentation.
Tratto
da
Sugar
Community
Edition
Documentation:
http://www.sugarcrm.com/crm/support/documentation/SugarCommunityEdit
ion/6.1/-­‐docs-­‐Developer_Guides-­‐Sugar_Developer_Guide_6.1.0-­‐
Chapter%202%20Application%20Framework.html#9000244
SugarCRM
Inc.
(2004).
SugarCRM
-­‐
Commercial
Open
Source
CRM.
Tratto
da
SugarCRM
-­‐
Commercial
Open
Source
CRM:
http://www.sugarcrm.com/crm/
The
Apache
Software
Foundation.
(2005).
Web
Service
-­‐
Axis.
Tratto
da
Apache
<Web
Services
>
Project:
http://axis.apache.org/axis/
The
Apache
Software
Foundation.
(2011).
Apache
Ant.
Tratto
da
The
Apache
Ant
Project:
http://ant.apache.org/
04/04/11
17
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike