ESF Submissions Web Service Developers ... - Ministry of Forests

learningsnortSecurity

Nov 3, 2013 (4 years and 9 months ago)

383 views









E
LECTRONIC
S
UBMISSION
F
RAMEWORK

Submissions Web Service


Client Developer’s Guide






Client:

Ministry of Forests and Range

Ministry of Environment

Date:

Dec 06, 2006

Revision:

1.4

















Vivid Solutions Inc.

Suite #1A, 2328 Governme
nt St.

Victoria, BC V8T 5G5

Phone: (250) 385
-
6040

Fax: (250) 385
-
6046

Website:
www.vividsolutions.com





MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
2

of
25



Document Change Control

REVISION
NUMBER

DATE OF ISSUE

AUTHOR(S)

DESCRIPTION

DRAFT

August 23, 200
4

Jason Sherman/Chris Boreen

Original draft

1.0

September 14, 2004

Jason Sherman/Chris Boreen

Release.

Added .Net code examples

1.1

December 09, 2004

Jason Sherman/Chris Boreen

Release.

Made changes to attached WSDL.
Added info regarding extended
audits
.

1.2

February 16, 2005

Chris Boreen

Updated production server URL to
reflect ESF server move.

1.3

April 11, 2006

Jason Sherman

New methods added for
Attachments. Configuration for
WebADE 4 updated.

1.4

Dec 06, 2006

Chris Boreen

Updated URLs for new
en
vironment.




MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
3

of
25



Table of Contents

1. INTRODUCTION

................................
................................
................................
.....................

5

2. SUBMISSIONS WEB S
ERVICE API

................................
................................
................................
..

6

2.1

METHODS

................................
................................
................................
..............

6

2.1.1

MAKESUBMISSION

................................
................................
..............................

7

2.1.2

GETSUBMISSIONSTATUS

................................
................................
.......................

7

2.1.3

GETSUPPORTEDSUBMISSI
ONTYPES

................................
................................
..........

7

2.1.4

ISSUPPORTEDSUBMISSIO
NTYPE

................................
................................
..............

7

2.1.5

SEARCHSUBMISSION

................................
................................
...........................

7

2.1.6

UPLOADSUBMISSION

................................
................................
...........................

8

2.1.7

GETSUPPORTEDATTACHME
NTTYPES

................................
................................
........

8

2.1.8

ADDATTACHMENT

................................
................................
.............................

8

2.2

DATA STRUCTURES

................................
................................
................................
..

8

2.3

EXCEPTIONS AND REQUE
ST FLOW

................................
................................
.................

9

3. SUBMI
SSIONS CLIENT

................................
................................
................................
..............

11

3.1

CLIENT API (SUBMISSI
ONSCLIENT)

................................
................................
.................

11

3.1.1

SUBMISSIONSCLIENT EX
CEPTIONS

................................
................................
...........

12

4. JAVA CODE EXAMPLE
S

................................
................................
................................
.............

14

4.1

REQUIREMENTS

................................
................................
................................
.......

14

4.2

CREATE A SUBMISSIONS
CLIENT

................................
................................
.....................

14

4.3

CALL GETSUPPORTEDSUB
MISSIONTYPES

................................
................................
..........

14

4.4

CALL ISSUPPORTEDSUBM
ISSIONTYPE

................................
................................
..............

15

4.5

CA
LL SEARCHSUBMISSIONS

................................
................................
..........................

15

4.6

CALL GETSUBMISSIONST
ATUS

................................
................................
......................

16

4.7

CALL MAKESUBMISSION

................................
................................
..............................

17

4.8

CALL UPLOADSUBMISSIO
N

................................
................................
...........................

17

4.9

CALL GETSUPPORTEDATT
ACHMENTTYPES

................................
................................
........

18

4.10

CALL ADDATTACHMENT

................................
................................
.............................

18

4.11

EXAMPLE OF ADDING FI
LE TO ATTACHMENT PAY
LOAD

................................
..........................

19

5. .NET CODE EXAMPLE
S

................................
................................
................................
.............

21

5.1

ADDING A WEB REFENCE

................................
................................
............................

21

MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
4

of
25


5.2

USING THE GENERATED
CLIENT

................................
................................
....................

22

6. APPENDIX A


ESF SUBMISSIONS WEB
SERVICE WSDL

................................
................................
..........

23

7. APPENDIX B


GENERATING AN AXIS C
LIENT

................................
................................
....................

24

7.1

GENERATING USING APA
CHE AXIS 1.1

................................
................................
.............

24

7.1.1

REQUIREMENTS FOR CLI
ENT GENERATION

................................
................................
.

24

7.1.2

GENERATING CLIENT ST
UB CLASSES WITH ANT

................................
............................

24

MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
5

of
25


INTRODUCTION

The purpose of this document is to introduce t
he Electronic Submissions Framework (ESF)
Submissions Web Service to developers responsible for implementing clients/consumers of
said service. This document will describe the application programming interface (API)
exposed by the web service (Submissions
) and how to generate code to call the service.


The Submissions web service is currently SOAP 1.1 (Simple Object Access Protocol) RPC
model service. The combination of RPC and encoding has been the most successful way to
deliver the data to ESF and to al
low interoperability for different clients.


Client code is based on the service’s Web Service Definition Language (WSDL


version
1.1). The WSDL is an XML
-
based language for describing web services and how to access
them.


MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
6

of
25


SUBMISSIONS WEB SERV
ICE API

The

Submissions Web Service API exposes all of the public functionality currently within the
ESF. Aspects such as security and parameters are shared across the website and web
service to ensure common functionality between the two components. The methods an
d
data types mentioned in this section are defined in detail by the WSDL document attached
in Appendix A of this document.

METHODS

The following documents the methods exposed by the service.


METHOD NAME

RETURN TYPE

PARAMETER NAME

DATA TYPE

makeSubmissio
n

SubmissionResult

submissionType

string



userReference

string



submissionData

string





getSubmissionStatus

SubmissionStatus

submissionId

long





getSupportedSubmissionTypes

Array Of SubmissionType

<none>






isSupportedSubmissionType

boolean

submissionType

string



version

integer





searchSubmission

Array Of SubmissionDetails

submissionType

string



status

string



userReference

string



submitterCode

string



submittedBy

string



fromDate

dateTime



toDate

dateTime



pageNumber

i
nteger



pageSize

integer





uploadSubmission

SubmissionResult

submissionType

string



userReference

string



originalFileName

string



useCurrentUserEmail

boolean



submissionData

string





getSupportedAttachmentTypes

Array of AttachmentType

su
bmissionType

string





addAttachment

AttachmentResult

submissionId

long



attachmentType

string



attachmentNote

string



originalFileName

string

MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
7

of
25


Table 2
-

Methods

MAKE
S
UBMISSION

This method is used to upload, validate, and finalize a new submission
. The XML file is
passed in as a string (submissionData parameter) thus clients are responsible for converting
the XML file to a string. Limitations on file size will be machine dependant as memory
heaps will affect how large a string can be created.


Th
e SubmissionResult will inform the client if the submission has succeeded. If
SubmissionResult.finalized is true, the submission was uploaded, validated and finalized and
the SubmissionResult.submissionId will have a non
-
zero value indicating the submissi
on id.
If the submission was not finalized, SubmissionResult.lastSuccessfulStage will indicate if the
submission was uploaded, or validated, or finalized. The SubmissionResult.errors array will
contain any validation error messages if the file was upload
ed but not validated.

NOTE
: A maximum submission size of 4 Megabyte is enforced in this generated client.

GET
S
UBMISSION
S
TATUS

This method is used to retrieve details for a specific submission. Given a submission id, the
method will return the same detai
ls as a search plus all status messages for that
submission. The status messages will contain audit messages if the caller has the
necessary privileges.

GET
S
UPPORTED
S
UBMISSION
T
YPES

This method will return all known and currently supported submission types
. No
parameters are expected.

IS
S
UPPORTED
S
UBMISSION
T
YPE

This method allows callers to query the service to determine if a specific submission type
and version is currently supported. This is useful for a client that may be tuned to submit a
particular ve
rsion of the submission document. It would be prudent for the client to test
the document type and version before submitting. Of course this check will done by the ESF
when the submission is being made as well.

SEARCH
S
UBMISSION

This method is used to re
turn a listing of known submissions that matches the search
criteria. Results are returned in pages; page number and the size of pages are passed in as
parameters. The default for pageNumber is 1, the default for pageSize is 20. All
parameters can be le
ft blank.


Once the submission of interest is located, a second call is normally made to
getSubmissionStatus to retrieve the details of the submission.


MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
8

of
25


UPLOAD
S
UBMISSION

This method is identical to makeSubmission with additional parameters. All newly
deve
loped Web Service clients should make use of this method.


New parameters are originalFileName (allows caller to name and identify the file that the
submissionData is created from) and useCurrentUserEmail (allows caller to specify which
email address the s
tatus messages are delivered to, the address in the submissionData or
the current User’s email address).

GET
S
UPPORTED
A
TTACHMENT
T
YPES

This method will return all known attachment types for a given submission type. The
results should be inspected to determi
ne which of the attachment types (if any) are
enabled.

ADD
A
TTACHMENT

This method allows the caller to add an attachment to a given submission. The submission
must be in an acceptable state (Submitted or In Progress) and the caller must be the
original sub
mitter.


The attachmentType parameter must be a supported attachmentType for the submission’s
submissionType. The attachmentNote parameter allows the caller to enter some context or
comments about this particular attachment. The originalFileName paramete
r allows the
caller to identify the attachment.


The AttachmentResult will inform the client if the submission has succeeded. If
AttachmentResult.finalized is true, the attachment was uploaded and saved and the
AttachmentResult.submissionAttachmentId will

have a non
-
zero value indicating the
submission attachment id. The AttachmentResult.errors array will contain any error
messages.


NOTE:

There is no attachmentFile parameter. The service expects one and only one file in
the attachment payload of the s
ervice request, not as a parameter. See the later examples
for adding a file to the attachment payload of the service request.



DATA STRUCTURES

The following documents the data structures used in the service.


STRUCTURE NAME

PROPERTY

DATA TYPE

Submissio
nDetails

submissionDate

dateTime


submissionType

string


statusCode

string


userReference

string


submissionId

long


submitter

string




MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
9

of
25


StatusMessage

extendedMessage

string


messageDate

dateTime


isAudit

boolean


message

string




SubmissionSt
atus

submissionDate

dateTime


submissionType

string


statusCode

string


userReference

string


submissionId

long


Submitter

string


statusMessages

Array of StatusMessage




SubmissionResult

lastSuccessfulStage

string


submissionId

long


finalized

boolean


errors

Array of string




SubmissionType

displayName

string


version

integer


name

string




AttachmentResult

lastSuccessfulStage

string


submissionId

long


submissionAttachmentId

long


finalized

boolean


errors

Array of string




Att
achmentType

name

string


description

string


enabled

boolean




Table 1


Data Structures

EXCEPTIONS AND REQUE
ST FLOW

There are three stages to each service request: initialize an ESF session, perform security
check on user/method, and the method call
itself. Exceptions can be thrown at any of the
three stages.



Each request goes through a session initialization handler to ensure that ESF is available
and ready to accept the requests. Each request then falls to a security handler to ensure
that the c
aller has the privileges to request that method. An AxisFault can be thrown at
either of these stages if the session fails to initialize or the user does not have the required
security. AxisFault maps directly to a SOAPException.


Each of the methods wil
l throw a SubmissionsFault if any known exception is raised during
the execution of the method (i.e. unexpected parameter, data access error, SQL error).
MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
10

of
25


SubmissionsFault maps to a SOAPException, but some clients will be able to identify these
specific ex
ceptions from other SOAPExceptions.


AxisFault and SubmissionsFault map to SOAPException. Depending on how the client is
generated will depend on what exceptions are recognized. AXIS generated clients will
recognize AxisFault and SubmissionFault and can
view the details in faultString. Other
clients may only recognize their own variant of SOAPException but should provide some
access to the details.


Please note that the tools used to create client code from the WSDL will generate their own
exception cla
sses. They may just be java.rmi.RemoteException and any way of determining
the cause will be in the exception’s message.

MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
11

of
25


SUBMISSIONS CLIENT

A framework has been developed to aid an ESF integrator to quickly make use of the
service. The client consists of

a generated AXIS client and a wrapper class which simplifies
the usage of the client. The wrapper class is SubmissionClient and the rest are stock
classes generated via the AXIS generator tool as specified in Appendix B.


PACKAGE

CLASS NAME

ca.bc.gov.mo
f.esf.ws.submissions.client

SubmissionsClient



ca.bc.gov.mof.esf.ws.submissions

Submissions


SubmissionsService


SubmissionsServiceLocator


SubmissionsServiceTestCase


SubmissionsSoapBindingStub



ca.bc.gov.mof.esf.ws.submissions.faults

Submission
sFault



ca.bc.gov.mof.esf.ws.submissions.model

StatusMessage


SubmissionDetails


SubmissionResult


SubmissionStatus


SubmissionType


AttachmentResult


AttachmentType

Table 3


Generated Java Classes

CLIENT API (SUBMISSI
ONSCLIENT)

Another layer of

abstraction has been added to make a simpler, developer
-
friendly API.
This class (
ca.bc.gov.mof.esf.ws.submissions.client
.
SubmissionsClient
) could be
used by developers wishing to make a user interface to the Submissions Web Service.


METHOD NAME

RETURN
TYPE

PARAMETER NAME

DATA TYPE

SubmissionsClient

Constructor

url

String



username

String



password

String





makeSubmission

SubmissionResult

submissionType

String



userReference

String



filename

String





getSubmissionStatus

SubmissionStatus

submissionId

long





getSupportedSubmissionTypes

List (
SubmissionType
)

<none>






isSupportedSubmissionType

boolean

submissionType

String

MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
12

of
25




version

int





searchSubmission

List (SubmissionDetails)

submissionType

String



statusCode

String



use
rReference

String



submitterCode

String



submittedBy

String



fromDate

java.util.Date



toDate

java.util.Date



pageNumber

int



pageSize

int





uploadSubmission

SubmissionResult

submissionType

String



userReference

String



originalFileName

String



useCurrentUserEmail

boolean



filename

String





getSupportedAttachmentTypes

List (
AttachmentType
)

submissionType

String





addAttachment

AttachmentResult

submissionId

long



attachmentType

String



attachmentNote

String



originalFileN
ame

String



filename

String





getAddress

String

<none>


setAddress

<none>

value

String

getUsername

String

<none>


setUsername

<none>

value

String

getPassword

String

<none>


setPassword

<none>

value

String

getTimeout

Int

<none>


setTimeout

<non
e>

value

int

Table 4


SubmissionsClient Methods


This API allows developers to create a SubmissionClient, provide a specific address for the
service, provide credentials to log into the server and throw known exceptions.


S
UBMISSIONS
C
LIENT
E
XCEPTIONS

The

API exposes any possible exception that may be encountered. It is up to the developer
to handle them and decide how best to present them to the end user.


EXCEPTION TYPE

THROWN BY

LIKELY REASON

java.net.MalformedURLException

makeSubmission

getSubmission
Status

The address to the web service cannot be
parsed into a valid url. Does not mean that
the address is invalid, just malf
ormed.

MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
13

of
25


getSupportedSubmissionTypes

isSupportedSubmissionType

searchSubmission

uploadSubmission

getSupportedSubmissionTypes

addAttachment




javax.xml.rpc.ServiceException

makeSubmission

getSubmissionStatus

getSupportedSubmissionTypes

isSupportedSubmissionType

searchSubmission

uploadSubmission

getSupportedSubmissionTypes

addAttachment

Thrown when the generated classes encounter
an e
rror setting the url or service name.




SubmissionsFault

makeSubmission

getSubmissionStatus

getSupportedSubmissionTypes

isSupportedSubmissionType

searchSubmission

uploadSubmission

getSupportedSubmissionTypes

addAttachment

This is our own exception class
. This is
thrown when a known exception occurs on the
server side. This could encapsulate any
number of errors from SQL errors to business
errors (such as invalid submission type).
There should be a descriptive message
included that will divulge more in
formation.




java.rmi.RemoteException

makeSubmission

getSubmissionStatus

getSupportedSubmissionTypes

isSupportedSubmissionType

searchSubmission

Any unhandled/untyped exceptions from the
server. These could include security
exceptions, session initializ
ation exceptions,
parsing exceptions, etc.




java.io.FileNotFoundException

makeSubmission

uploadSubmission

addAttachment

The filename specified cannot be found.




java.io.IOException

makeSubmission

uploadSubmission

addAttachment

An error occurred rea
ding the file.




java.lang.OutOfMemoryError

makeSubmission

uploadSubmission

The system ran out of memory as it converted
the contents of the file to a string. This is a
necessary step as the file’s contents are
pa獳sd as on攠獴ring in the pl䅐 m敳eag攮

Table 5


SubmissionsClient Exceptions

MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
14

of
25


JAVA CODE EXAMPLES

The following are examples of how to call the SubmissionsClient class to access the
Submissions web service.

REQUIREMENTS

For the generated code and the SubmissionsClient code to work, certain lib
raries must be
available. The source and test classes have been developed and run under JDK 1.4.2_06.


From the AXIS 1.2.1 Distribution



axis
-
ant.jar (only required to use ANT to generate the stub classes)


From the MoF Standard Excluded Libraries



commons
-
logging
-
01_00_04.jar



log4j
-
01_02_12.jar



xercesImpl
-
02_07_01.jar



xml
-
apis
-
02_07_01.jar


From the MoF Standard Included Libraries



activation
-
01_00_02.jar



axis
-
01_02_01.jar



jaxrpc
-
01_01_00.jar



mail
-
01_03_03.jar



saaj
-
01_02_00.jar



wsdl4j
-
01_05_01.jar


CREATE A

SUBMISSIONSCLIENT


String address = "http://localhost:8080/esf/services/Submissions";

String uname = "myDomain/myUsername";

String pwd = "myPassword";


SubmissionsClient client = new SubmissionsClient(address, uname, pwd);

CALL GETSUPPORTEDSUB
MISSIONTYPES

List results = new ArrayList();


try {


results = client.getSupportedSubmissionTypes();


assertTrue(results.size() > 0);


Iterator iter = results.iterator();


while (iter.hasNext()){


SubmissionType obj = (SubmissionType) iter.next();



System.out.println("name: " + obj.getName());


System.out.println("version: " + obj.getName());


System.out.println("display: " + obj.getVersion());

MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
15

of
25



}

} catch (MalformedURLException e) {


e.printStackTrace(System.err);


fail(
e.getMessage());

} catch (ServiceException e) {


e.printStackTrace(System.err);


fail(e.getMessage());

} catch (SubmissionsFault e) {


e.printStackTrace(System.err);


fail(e.getMessage());

} catch (RemoteException e) {


e.printStackTrace
(System.err);


fail(e.getMessage());

}

CALL ISSUPPORTEDSUBM
ISSIONTYPE

boolean result = false;

String submissionType = "ABR";

int version = 1;

try {


result = client.isSupportedSubmissionType(submissionType, version);


System.out.println("IsSupportedSu
bmissionType? " + result);

} catch (MalformedURLException e) {


e.printStackTrace(System.err);

} catch (ServiceException e) {


e.printStackTrace(System.err);

} catch (SubmissionsFault e) {


e.printStackTrace(System.err);

} catch (RemoteException e)
{


e.printStackTrace(System.err);

}

CALL SEARCHSUBMISSIO
NS

List results = new ArrayList();

String submissionType = null;

String status = null;

String userReference = null;

String submitterCode = null;

String submittedBy = null;

Date fromDate = null;

Date
toDate = null;

int pageNumber = 1;

int pageSize = 20;



try {


results = client.searchSubmissions(submissionType,


status,


userReference,


submitterCode,


submittedBy,


fromDate,

MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
16

of
25



toDate,


pageNumber,


p
ageSize);



Iterator iter = results.iterator();


int i = 1;


while (iter.hasNext()){


SubmissionDetails result = (SubmissionDetails) iter.next();


System.out.println(i + ").............................");


System.out.println("
id: " + result.getSubmissionId());


System.out.println("type: " + result.getSubmissionType());


System.out.println("status: " + result.getStatusCode());


System.out.println("submitted by: " + result.getSubmitter());


System.out.
println("user ref: " + result.getUserReference());


System.out.println("date: " + result.getSubmissionDate());


i++;


}

} catch (MalformedURLException e) {


e.printStackTrace(System.err);

} catch (ServiceException e) {


e.printStackT
race(System.err);

} catch (SubmissionsFault e) {


e.printStackTrace(System.err);

} catch (RemoteException e) {


e.printStackTrace(System.err);

}

CALL GETSUBMISSIONST
ATUS

SubmissionStatus result = null;

long submissionId = 425;


try {


result =

client.getSubmissionStatus(submissionId);


System.out.println("................................");


System.out.println("id: " + result.getSubmissionId());


System.out.println("type: " + result.getSubmissionType());


System.out.println("status:

" + result.getStatusCode());


System.out.println("submitted by: " + result.getSubmitter());


System.out.println("user ref: " + result.getUserReference());


System.out.println("date: " + result.getSubmissionDate());


for (int i = 0; i < result.
getStatusMessages().length; i++) {


StatusMessage msg = result.getStatusMessages()[i];


System.out.println(" " + (i+1) + "...........");


System.out.println(" msg: " + msg.getMessage());


System.out.println(" msg ext: " + msg
.getExtendedMessage());


System.out.println(" msg date: " + msg.getMessageDate());


System.out.println(" audit?: " + msg.isIsAudit());


}

} catch (MalformedURLException e) {


e.printStackTrace(System.err);

} catch (ServiceException e)

{


e.printStackTrace(System.err);

} catch (SubmissionsFault e) {


e.printStackTrace(System.err);

MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
17

of
25


} catch (RemoteException e) {


e.printStackTrace(System.err);

}


CALL MAKESUBMISSION

SubmissionResult result = new SubmissionResult();

String sub
missionType = "ESFTEST";

String userReference = "myUserreference";

String filename = "c:/goodsubmission.xml";


try {


result = client.makeSubmission(submissionType, userReference, filename);


System.out.println("finalized = " + result.isFinalized());


System.out.println("submissionId = " + result.getSubmissionId());


System.out.println("stage = " + result.getLastSuccessfulStage());


String[] errs = result.getErrors();


for (int i = 0; i < errs.length; i++) {


System.out.println((i+1
) + ") " + errs[i]);


}

} catch (MalformedURLException e) {


e.printStackTrace(System.err);

} catch (ServiceException e) {


e.printStackTrace(System.err);

} catch (SubmissionsFault e) {


e.printStackTrace(System.err);

} catch (RemoteExcepti
on e) {


e.printStackTrace(System.err);

} catch (FileNotFoundException e){


e.printStackTrace(System.err);

} catch (IOException e) {


e.printStackTrace(System.err);

} catch (OutOfMemoryError e) {


e.printStackTrace(System.err);

}

CALL UPLOADSUB
MISSION

SubmissionResult result = new SubmissionResult();

String submissionType = "ESFTEST";

String userReference = "myUserreference";

String originalFileName = "goodsubmission.xml";

boolean useCurrentUserEmil = true;

String filename = "c:/esfdata/" + orig
inalFileName;


try {


result = client.uploadSubmission(submissionType, userReference,
originalFileName, useCurrentUserEmail, filename);


System.out.println("finalized = " + result.isFinalized());


System.out.println("submissionId = " + result.getS
ubmissionId());


System.out.println("stage = " + result.getLastSuccessfulStage());


String[] errs = result.getErrors();


for (int i = 0; i < errs.length; i++) {

MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
18

of
25



System.out.println((i+1) + ") " + errs[i]);


}

} catch (MalformedURLExcepti
on e) {


e.printStackTrace(System.err);

} catch (ServiceException e) {


e.printStackTrace(System.err);

} catch (SubmissionsFault e) {


e.printStackTrace(System.err);

} catch (RemoteException e) {


e.printStackTrace(System.err);

} catch (Fil
eNotFoundException e){


e.printStackTrace(System.err);

} catch (IOException e) {


e.printStackTrace(System.err);

} catch (OutOfMemoryError e) {


e.printStackTrace(System.err);

}

CALL GETSUPPORTEDATT
ACHMENTTYPES

List results = new ArrayList();

Stri
ng submissionType = "MYSUB";

try {


results = client.getSupportedAttachmentTypes(submissionType);


assertTrue(results.size() > 0);


Iterator iter = results.iterator();


while (iter.hasNext()){


AttachmentType obj = (AttachmentType) iter.
next();


System.out.println("name: " + obj.getName());


System.out.println("description: " + obj.getDescription());


System.out.println("enabled: " + obj.isEnabled());


}

} catch (MalformedURLException e) {


e.printStackTrace(Sys
tem.err);


fail(e.getMessage());

} catch (ServiceException e) {


e.printStackTrace(System.err);


fail(e.getMessage());

} catch (SubmissionsFault e) {


e.printStackTrace(System.err);


fail(e.getMessage());

} catch (RemoteException e) {



e.printStackTrace(System.err);


fail(e.getMessage());

}

CALL ADDATTACHMENT

AttachmentResult result = new AttachmentResult();

long submissionId = 71;

String attachmentType = "ATTONE";

String attachmentNote = "myAttachmentNote";

String originalFileName
= "extradata.pdf";

String filename = "c:/esfdata/" + originalFileName;

MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
19

of
25



try {


result = client.addAttachment(submissionId, attachmentType,
attachmentNote, originalFileName, filename);


System.out.println("finalized = " + result.isFinalized());


Sy
stem.out.println("submissionId = " + result.getSubmissionId());


System.out.println("submissionAttachmentId = " +
result.getSubmissionAttachmentId());


System.out.println("stage = " + result.getLastSuccessfulStage());


String[] errs = result.getEr
rors();


for (int i = 0; i < errs.length; i++) {


System.out.println((i+1) + ") " + errs[i]);


}

} catch (MalformedURLException e) {


e.printStackTrace(System.err);

} catch (ServiceException e) {


e.printStackTrace(System.err);

} catch (
SubmissionsFault e) {


e.printStackTrace(System.err);

} catch (RemoteException e) {


e.printStackTrace(System.err);

} catch (FileNotFoundException e){


e.printStackTrace(System.err);

} catch (IOException e) {


e.printStackTrace(System.err);

} catch (OutOfMemoryError e) {


e.printStackTrace(System.err);

}

EXAMPLE OF ADDING FI
LE TO ATTACHMENT PAY
LOAD

public void testSubmissionsAddAttachment() throws Exception {


SubmissionsSoapBindingStub binding;


try {


binding = (SubmissionsSoapBind
ingStub) new
SubmissionsServiceLocator().getSubmissions();


} catch (ServiceException jre) {


if(jre.getLinkedCause()!=null)


jre.getLinkedCause().printStackTrace();


throw new junit.framework.AssertionFailedError("JAX
-
RPC ServiceException
caught: "

+ jre);


}


assertNotNull("binding is null", binding);



// Time out after a minute


binding.setTimeout(60000);


binding.setUsername("myUsername");


binding.setPassword("myPassword");




long submissionId = 71;


String attachmentType = "myAttachm
entType";


String attachmentNote = "myAttachmentNote";


String originalFileName = "data.pdf";


File file = new File("c:/esfdata/" + originalFileName);



MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
20

of
25



//from the java activation framework...


FileDataSource fds = new FileDataSource(file);


DataHa
ndler dh = new DataHandler(fds);


//add the data handler to the attachment payload


binding.addAttachment(dh);




// Test operation


try {


AttachmentResult value = null;


value = binding.addAttachment(submissionId, attachmentType,
attachmentNote
, originalFileName);


} catch (SubmissionsFault e1) {


throw new junit.framework.AssertionFailedError("SubmissionsFault
Exception caught: " + e1);


}


// TBD
-

validate results

}

MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
21

of
25


.NET CODE EXAMPLES

This section will give an example of how to create

an ESF Submissions Service client using
Microsoft Visual Studio. The examples contained here were done with Microsoft
Development Environment 2002


Visual Basic .NET.

ADDING A WEB REFEREN
CE

The first step in making use of a Web Service in a project is t
o add a Web Reference.
The “Add Web Reference…” functionality can be found under the “Project” menu.
This dialog is normally used to connect to a UDDI service or a URL in order to
retrieve the WSDL document so you will need to type in the local path to t
he location
of the WSDL file.


If your machine is connected to the Internet and the ESF service is available, you
can get the latest WSDL document directly from the ESF itself. This will ensure you
are always using the latest definition. Simply type in t
he address of the service with
a parameter on the end indicating you would like to view the WSDL. An example of
the production URL would be the following:


http://esfws.for.gov.bc.
ca/esf/services/Submissions?WSDL


You will be prompted for credentials in order to access the WSDL. The user simply
needs to be authenticated to read the WSDL and does not have to have any specific
role within the ESF.




Once the “Web Reference” has be
en added to the project, client code is generated in
the background and is available for use. You will see the newly added reference in
the Solution Explorer and it will be named after the URL you used or it will be called
MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
22

of
25


WebReference1 if you loaded the
WSDL from a file. Below is an example of what you
will see if you used a URL to load the WSDL. The reference can be renamed to suit
your preferences without causing any problems.



USING THE GENERATED
CLIENT

Once the Submissions Web Service client code
is generated, it is very simple to start
making use of the code to complete a call to the ESF Submissions Web Service.
Below is an example in Visual Basic .NET using the Web Reference created above:


Dim stub As New ca.bc.gov.for.testextranet5.Submissions
Service()

Dim credentials As New System.Net.NetworkCredential(“user”, “pass”, “domain”)

stub.Credentials = credentials


stub.Url = “http://testextranet5.for.gov.bc.ca/esf/services/Submissions”

stub.Timeout = 90 * 1000 ’90 seconds. Value is set in milli
seconds.


Dim types() As ca.bc.gov.for.testextranet5.SubmissionType

types = stub.getSupportedSubmissionTypes()

MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
23

of
25


APPENDIX A


ESF SUBMISSIONS WEB
SERVICE WSDL

The ESF Submissions Web Service is attached:




NOTE
: Some of the values may ch
ange depending on the server in which the service is
hosted. The latest WSDL for the service can always be retrieved from the service itself:


http://server.hostname:port/esf/servic
es/Submissions?WSDL


The production service will be located at the following location:


http://esfws.for.gov.bc.ca/esf/services/Submissions?WSDL



The test service will be located a
t the following location:


http://testesfws.for.gov.bc.ca/esf/services/Submissions?WSDL


MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
24

of
25


APPENDIX B


GENERATING AN AXIS C
LIENT

GENERATING USING APA
CHE AXIS 1.1

The following sec
tion will document how to generate code for an Apache AXIS 1.1 client.
AXIS is Apache’s implementation of SOAP. Axis provides tools to generate client code
(Java) from the WSDL. The tools integrate nicely with Apache Ant (1.5.1 or later) to allow
ease o
f generation.

R
EQUIREMENTS FOR
C
LIENT
G
ENERATION



JDK 1.3.1_08 (or later)



Apache AXIS 1.1



Apache ANT 1.5.1 (or later)

G
ENERATING
C
LIENT
S
TUB
C
LASSES WITH
ANT

To declare the tasks, set up a classpath to include the axis task JAR and all the dependent
librari
es. Including everything in the axis lib directory should suffice.



<path id="master
-
classpath">


<fileset dir="${lib.dir}">


<include name="axis.jar"/>


<include name="commons
-
discovery.jar"/>


<include name="commons
-
logging.jar"/>


<include name="jaxrpc.jar"/>


<include name="log4j
-
1.2.8.jar"/>


<include name="saaj.jar"/>


<include name="wsdl4j.jar"/>


<include name="activation
-
01_00_01.jar"/>


<include name="xercesImpl
-
02_04_00.jar"/>


<inc
lude name="xmlParserAPIs
-
02_04_00.jar"/>


<include name="axis
-
ant.jar"/>


<include name="junit_3_8_1.jar"/>


</fileset>


</path>


Then use the <taskdef> declaration to declare all the tasks listed in a properties file inside
the axis
-
ant.ja
r file:



<taskdef classpathref="master
-
classpath" resource="axis
-
tasks.properties"/>


Then create the java classes from an existing WSDL:



<target name="generate
-
client
-
stub>


<delete dir="${generated.dir}"/>


<mkdir dir="${generated.dir}"/>


<axis
-
wsdl2java


output="${generated.dir}"


verbose="true"

MoF/MSRM

Su
bmissions Web Service


Client Developer’s Guide


Page
25

of
25



url="http://server:port/esf/services/Submissions?WSDL"


serverside="false"


skeletondeploy="false"


testcase="true"


username="${serv
er.username}"


password="${server.password}"


debug="false">


<mapping namespace="http://server:port/esf/services/Submissions"
package="ca.bc.gov.mof.esf.ws.submissions "/>


</axis
-
wsdl2java>


</target>