The original getFishTicketNumbers() registered your request and then returned the same list of numbers at every request. As a result users had to scan the list and remove any numbers that had previously been used. The fish ticket numbers were also returned as interm ticket numbers rather than real ticket numbers.
This replacement method is intended to be more straight forward. Each request will reserve and return N numbers that the user has never received before.
Reserves and returns one or more fish ticket numbers in the database for your user. Other users will not be given these numbers in their requests as they are reserved for your use. This is provided to help preserve id uniqueness of these fish ticket numbers.
All eLandings landings reports have one or more fish_ticket_numbers associated. There is one fish_ticket_number per CFEC permit holder on the landing report. Before assigning a fish_ticket_number to a new report, eLandings and all third-party users need to verify that the fish_ticket_numbers that they assign are not already in use. Otherwise, previous report data will be lost and new report data may be corrupted.
For example:
A landing report is created by userid=Bob and the landing report is assigned fish_ticket_number = 1000
A landing report is created by userid=Joe and the landing report is assigned fish_ticket_number =1000
The header information for the record created by Bob will be replaced by the header information created by Joe. If Bob's report had more permit items than Joe, then Joe's report might contain his line items and Joe's permit items. Bob will be angry at eLandings and at Joe.
To avoid this situation in eLandings situations or in third-party tools, eLandings provides the means to get and reserve a list of fish_ticket_numbers in such a way than anyone else that asks for an available fish ticket number will not be provided with these reserved numbers. As long as everyone honors this rule, we can avoid collisions and data loss.
We cannot prevent users from illegally re-using a fish_ticket_number. eLandings allows users to save their changes. It is very hard to determine if a change should be labeled illegal reuse or normal user data changes.
This method returns a list of reserved fish ticket numbers as a string in XML format as defined by the XSD definition for number_info object in dataelements.xsd. If errors were encountered while retrieving the landing report in the web service, an empty number_info object will be returned containing a list of messages objects as defined by the dataelements.xsd definition for messages elements.
The getFishTicketNumbers001() takes five arguments:
- String Userid – i.e "amarx"
- String password – i.e. "A_marx"
- String schemaVersionNumber – i.e. "2.1"
- String numberOfNumbersRequested - i.e. "10"
- String reportType - i.e. "B" for Salmon, "C" for Crab, "G" for groundfish
In this replacement webservice method for getFishTicketNumbers() we no longer ask for the operation type.
If we pass in a numberOfNumbersRequested=10, we are asking for 10 new fish_ticket_numbers from the database that have never been used and will be reserved for our use.
In the web service client we might auto generate a data structure by providing the web service url. In eLandings we use Java – JAX-WS and generated a structure called ReportManager.
ReportManagement ws;
...
...
String xml = ws.getFishTicketNumbers001(userid, password, schemaVersionNumber, numberOfNumbersRequested, reportType);
Or
String xml = ws.getFishTicketNumbers001("amarx", "A_marx", "2.3", 10, "B");
Notice that we are passing in "B" for the reportType. This indicates that we intend to use these fish tickets on salmon fish ticket. However, if you pass in "G" and get back tickets that you intended to use on Groundfish tickets and then happened to use them on Salmon tickets, the system will accept them when you submit the ticket later on.
If the web service call was successful you might see a string containing something like:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<number_info>
<schema_version>2.3</schema_version>
<fish_ticket_number>E12 685779</fish_ticket_number>
<fish_ticket_number>E12 685780</fish_ticket_number>
<fish_ticket_number>E12 685781</fish_ticket_number>
<fish_ticket_number>E12 685782</fish_ticket_number>
<fish_ticket_number>E12 685783</fish_ticket_number>
<fish_ticket_number>E12 685784</fish_ticket_number>
<fish_ticket_number>E12 685785</fish_ticket_number>
<fish_ticket_number>E12 685786</fish_ticket_number>
<fish_ticket_number>E12 685787</fish_ticket_number>
<fish_ticket_number>E12 685788</fish_ticket_number>
</number_info>
If you call the webservice again using:
xml = ws.getFishTicketNumbers001("amarx", "A_marx", "2.3", 10, "B");
You would get back 10 new fish ticket numbers that this user has never seen before. These numbers are now reserved and should never be issued from this webservice method again.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<number_info>
<schema_version>2.3</schema_version>
<fish_ticket_number>E12 685789</fish_ticket_number>
<fish_ticket_number>E12 685790</fish_ticket_number>
<fish_ticket_number>E12 685791</fish_ticket_number>
<fish_ticket_number>E12 685792</fish_ticket_number>
<fish_ticket_number>E12 685793</fish_ticket_number>
<fish_ticket_number>E12 685794</fish_ticket_number>
<fish_ticket_number>E12 685795</fish_ticket_number>
<fish_ticket_number>E12 685796</fish_ticket_number>
<fish_ticket_number>E12 685797</fish_ticket_number>
<fish_ticket_number>E12 685798</fish_ticket_number>
</number_info>
If you pass in NULL for the report type with the following webservice call:
String xml = svc.getFishTicketNumbers001("amarx", "A_marx", "2.3", count, null);
you will get back an error message:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<number_info>
<messages>
<message severity_desc="ERROR" severity_code="E" msgid="1483">Report Type is required</message>
</messages>
<schema_version>2.6</schema_version>
</number_info>