Tutorial 06 - Working with eLandings Codes

For the completed code from this exercise see ElandingsClient.zip

The eLandings Look-up Codes files (i.e. Species Codes, Stat Areas Codes, Condition Codes, Gear Codes, etc.) are available for download at:
eLandings Look-up Code Files in XML format and eLandings Look-up Code Files in Human readable format

Download https://elandings.alaska.gov/elandings/XmlCodesLookup?event=xml&xml=species and save it to a file called species.xml within your Netbeans eLandingsClient project.

Within eLandings, we use these lookup code files to:

1. Validate a users data entry within a field

In eLandings, users create landing reports. Each landing report requires the user to define what type of species was caught while fishing. eLandings has a list of accepted species codes. Users are able to type in the species code quicker than typing in the full name of the species. eLanding can then check the species code list to see if the the user entered a species code that is recognized by eLandings.

2. Provide a user with a list of choices

In eLandings, while creating a landing report, users can define how fish were refrigerated on-board the vessel. These refrigeration or chill types are known as Chill codes. eLandings can dynamically create a dropdown combo-box listing all of the chill types available for a user to select from.

3. Communicate information concisely

When eLandings web service encounters a problem, the error, warning or information can often be described with a common message code. The web service client can look up the message id to display the information in a human readable form or lookup additional information associated with the message code.

You may also want to use eLandings codes within the web service client for similar purposes.

To work with eLandings codes download the Codes XSD file from the XML Schema page and save it to codes.xsd within your eLandingsClient project. For the test, training and production like see:
XML Resources and Documentation

We will be repeating several of the steps described in Tutorial 02 - Basic Connection + XML Handling

Go back to NetBeans
Right click on the Source Packages>New>Other

Click on

XML
JAXB Binding
Next

Next, give it a name like codes. Then point it at the codes.xsd file that you placed in your Netbeans ElandingsClient project root. Then click Finished.

Netbeans will generate a number of java classes in Generated Sources (jaxb) folder.

Open the ELandingsClient.java file.

Within the main method copy and paste in the following code:

//Create a generatic unmarshaller
javax.xml.bind.JAXBContext jaxbCtx = javax.xml.bind.JAXBContext.newInstance("generated");
javax.xml.bind.Unmarshaller unmarshaller = jaxbCtx.createUnmarshaller();

//Read in the species.xml file and parse it into a Codes object.
FileInputStream input = new FileInputStream("species.xml");
Codes codes =(Codes)unmarshaller.unmarshal(input);

//Get the list of species contained within the codes object, iterate over the list and display the species codes and names found therein.
List<SpeciesDef> species = codes.getSpeciesDef();
for(SpeciesDef speciesDef:species){
   System.out.println("Species "+speciesDef.getSpecies().getName()+" -- "+speciesDef.getSpecies().getValue().toString());
}

You now have a list of all the species codes that eLandings currently accepts. This approach can be used to load statareas, gear codes, chill types, etc. Typically, eLandings creates a resource jar file containing all of the lookup code files. These code files can then be bundled with a release.

Be aware that every year, a few minor changes are made to these code files. For example, once a year, a new species might be added or modified within the species.xml file.

This code assumes that we created a JAXB binding file in a default generated location. If you don't put a package name in to the create JAXB binding dialog on creation, Netbeans will put the files in the "generated" subfolder. If you already have files in the "generated" folder, for example from landingreport.xsd, those files will be deleted. If you try to create an unmarshaller with "generated" subfolder and have codes.xsd files rather than landingreport.xsd files, you will get odd behaviors when unmarshalling a landingreport.xsd defined object.

For example, if you attempt to unmarshall a xml string into a LandingReportInfo Object, you will get an error like:
javax.xml.bind.UnmarshalException: unexpected element (uri:"", local:"landing_report_info"). Expected elements are <{}address>,<{}adfg_region>,<{}admin>,<{}agency>,<{}agency_effort>,<{}agency_entered_stat_area>,<{}agency_stat_area>,<{}aleut_is_sable_rock_fishery>,<{}announcement_id>,<{}authorized_operation>,<{}authorized_user>,<{}avg_gear_depth>,<{}avg_sea_depth>,<{}background>,<{}batch_number>,<{}batch_office_code>,<{}batch_year>,<{}bed_code>,<{}bed_def>,<{}bedcode_required>,<{}begin_buoy_number>,<{}begin_depth>,<{}begin_latitude>,<{}begin_longitude>,<{}bird_avoidance_gear>,<{}block>,<{}build_number>,<{}business_name>,<{}buying_station_name>,<{}can_be_parent>,<{}cfec_fishery_def>,<{}cfec_id>,<{}cfec_permit>,<{}cfec_salmon_area>,<{}charter_activity_flag>,<{}checkin_date>,<{}checkout_date>,<{}child_operations>,<{}chill_def>,<{}chill_type>,<{}city>,<{}coar_region>,<{}coast_guard_number>,<{}coded_comment>,<{}codes>,<{}color>,<{}column_name>,<{}comment_code>,<{}comment_date>,<{}comment_def>,<{}comment_text>,<{}company>,<{}component>,<{}condition_code>,<{}condition_def>,<{}constant>,<{}copy_mail_address>,<{}corrective_action>,<{}count>,<{}count_required>,<{}country>,<{}crab_cdq_number>,<{}crew_size>,<{}cruise_number>,<{}date_fishing_began>,<{}date_of_landing>,<{}days_fished>,<{}deadloss_weight>,<{}default_date_fishing_began>,<{}default_fishing_period>,<{}default_nearest_bay_or_headland>,<{}default_number_of_fish_tickets_to_print>,<{}default_number_of_tally_sheets_to_print>,<{}default_operation_id>,<{}default_stat_area>,<{}default_time_of_landing>,<{}delivery_latitude>,<{}delivery_longitude>,<{}delivery_port_region>,<{}delivery_time>,<{}delivery_type>,<{}deploy_entry_seq>,<{}depth_unit_of_measure>,<{}description>,<{}destination_mail_address>,<{}diagnostic_event_id>,<{}disabled>,<{}discard_report>,<{}discard_report_def>,<{}display_on_login>,<{}disposition_code>,<{}disposition_def>,<{}dock_delivery>,<{}document_name>,<{}dual_permit>,<{}dungeness_crab_mgmt_district>,<{}duration>,<{}effectivity_date>,<{}effectivity_end_date>,<{}effort>,<{}effort_required>,<{}effort_unit_of_measure>,<{}email>,<{}email_agency_users>,<{}email_client>,<{}email_processor_users>,<{}email_schema_users>,<{}email_system>,<{}end_buoy_number>,<{}end_datetime>,<{}end_depth>,<{}end_entry_seq>,<{}end_latitude>,<{}end_longitude>,<{}entry_seq>,<{}entry_time>,<{}entry_type>,<{}event>,<{}expanded_fishery_id>,<{}export_directory>,<{}failed_login_attempts>,<{}fax>,<{}fed_area>,<{}federal_crab_permit_number>,<{}federal_gear_code>,<{}federal_permit_number>,<{}federal_processor_number>,<{}file_name>,<{}file_needed>,<{}final_report_visibility>,<{}first_name>,<{}fish_ticket_number>,<{}fish_ticket_number_request_date>,<{}fish_ticket_number_request_increment>,<{}fish_ticket_number_threshold>,<{}fish_ticket_password>,<{}fish_ticket_seq>,<{}fish_ticket_userid>,<{}fishery>,<{}fishery_area>,<{}fishery_name>,<{}fishing_activity_flag>,<{}fishing_period>,<{}floating>,<{}fmp_area>,<{}fmp_area_def>,<{}freezer_flag>,<{}from_build_number>,<{}from_mail_address>,<{}from_version_label>,<{}fuel>,<{}gear>,<{}gear_def>,<{}gear_deployment_time>,<{}gear_id>,<{}gear_lost>,<{}gear_retrieval_time>,<{}gear_set>,<{}gear_type>,<{}generate_tally_with_ticket>,<{}gross_tonnage>,<{}groundfish_mgmt_area>,<{}groundfish_mgmt_district>,<{}group_code>,<{}hail_weight>,<{}harvest_code>,<{}harvest_def>,<{}haul_number>,<{}hold_tank>,<{}home_directory>,<{}hook_size>,<{}hook_spacing>,<{}hooks_per_skate>,<{}ice_and_slime>,<{}id_required>,<{}ifq_fishery>,<{}ifq_gear>,<{}ifq_management>,<{}ifq_permit>,<{}ifq_permit_class>,<{}ifq_permit_number>,<{}ifq_port_code>,<{}import_directory>,<{}indication>,<{}initiate_date_time>,<{}install_date>,<{}installed_by_user>,<{}interview>,<{}iphc_regulatory_area>,<{}ipq_permit>,<{}ipq_permit_number>,<{}item_number>,<{}king_crab_mgmt_area>,<{}king_crab_mgmt_district>,<{}label>,<{}landing_report_id>,<{}landing_report_number_request_date>,<{}landing_report_number_request_increment>,<{}landing_report_number_threshold>,<{}last_change_user>,<{}last_delivery_for_trip>,<{}last_login_date>,<{}last_name>,<{}last_successful_login_date>,<{}length>,<{}license_number>,<{}license_year>,<{}limited>,<{}line_item_comment>,<{}line_item_number>,<{}line_item_stat_area>,<{}line_item_usable>,<{}line_items_ifq_out_of_sync>,<{}lingcod_mgmt_district>,<{}live_tank>,<{}locale_code>,<{}location>,<{}log_file_name>,<{}logbook>,<{}logbook_id>,<{}logging_level>,<{}mag_stripe_read>,<{}mail_processor_address>,<{}management_area_def>,<{}management_program>,<{}management_program_def>,<{}management_program_participant_def>,<{}manual_ifq_report>,<{}max_avg_weight>,<{}max_effort>,<{}max_login_retrys>,<{}max_xmit_file_size>,<{}md5>,<{}message>,<{}message_def>,<{}message_text>,<{}messages>,<{}middle_initial>,<{}min_avg_weight>,<{}min_effort>,<{}msgid>,<{}multiple_ifq_permits>,<{}name_suffix>,<{}nearest_bay_or_headland>,<{}net_tonnage>,<{}nmfs_person>,<{}nmfs_person_id>,<{}no_change_after_date>,<{}no_deliveries>,<{}no_production>,<{}num_cfec_permit_lines>,<{}num_decimals_for_price>,<{}num_decimals_for_weight>,<{}num_discard_lines>,<{}num_grading_pricing_lines>,<{}num_ifq_permit_lines>,<{}num_itemized_catch_lines>,<{}num_of_cfec_permits>,<{}num_of_landing_reports>,<{}num_prod_report_lines>,<{}num_stat_area_ws_lines>,<{}number_info>,<{}observer>,<{}observer_info>,<{}observer_name>,<{}observers>,<{}observers_onboard>,<{}operating_system>,<{}operating_system_version>,<{}operation>,<{}operation_name>,<{}operation_type_def>,<{}operator_name>,<{}out_of_state>,<{}overlimit_in_effect>,<{}overlimit_species>,<{}overlimit_threshold>,<{}parameter_key>,<{}parameter_value>,<{}parent_company>,<{}parent_operation>,<{}parent_operation_codes>,<{}parm>,<{}partial_delivery>,<{}password>,<{}path_name>,<{}percent>,<{}permit_item_number>,<{}permit_number>,<{}phone>,<{}phone_system>,<{}port_def>,<{}port_of_landing>,<{}possible_causes>,<{}pounds>,<{}price>,<{}primary_userid>,<{}printed_copy>,<{}printed_document>,<{}proc_code>,<{}proc_code_owner>,<{}proc_code_processor>,<{}proc_effort>,<{}proc_stat_area>,<{}process>,<{}processor_user>,<{}processor_user_info>,<{}product_code>,<{}product_item_template>,<{}product_recovery_rate>,<{}product_type>,<{}production_report_id>,<{}production_report_usable>,<{}program>,<{}program_id>,<{}query_group>,<{}query_id>,<{}query_name>,<{}query_output_format>,<{}query_result>,<{}query_sql>,<{}query_xml_template>,<{}receipt_date>,<{}receipt_directory>,<{}reception_date>,<{}record_id>,<{}refrigerator_flag>,<{}region>,<{}registered_buyer_number>,<{}registered_crab_receiver>,<{}registered_crab_receiver_number>,<{}report_data>,<{}report_date>,<{}report_status_def>,<{}report_type_def>,<{}request_receipt_date_time>,<{}response_address>,<{}response_receipt_date_time>,<{}retained_weight>,<{}revoked>,<{}root_directory>,<{}rsw_temp>,<{}salmon_mgmt_area>,<{}salmon_mgmt_district>,<{}salmon_mgmt_unit_code>,<{}salmon_stat_area_name>,<{}save_date>,<{}scallop_mgmt_area>,<{}scallop_mgmt_district>,<{}schema_change_notify>,<{}schema_version>,<{}scientific_name>,<{}secret_answer>,<{}security_question>,<{}send_email_flag>,<{}sequence_ticket_end>,<{}sequence_ticket_start>,<{}set_number>,<{}severity>,<{}shaft_horsepower>,<{}show_price>,<{}size_grade>,<{}size_grade_template>,<{}skate_length>,<{}slide>,<{}smtp_server>,<{}sold_condition_def>,<{}sold_weight>,<{}southeast_shellfish_area>,<{}special_area>,<{}special_area_def>,<{}species>,<{}species_def>,<{}species_defaults_source>,<{}start_date>,<{}start_datetime>,<{}start_entry_seq>,<{}starting_font_size>,<{}stat_area>,<{}stat_area_def>,<{}stat_area_worksheet>,<{}state>,<{}status>,<{}substitution>,<{}tally_invoice>,<{}tanner_crab_mgmt_area>,<{}tanner_crab_mgmt_district>,<{}tanner_crab_mgmt_section>,<{}tare>,<{}target_species>,<{}tender_batch>,<{}tender_packer_flag>,<{}tender_trip_number>,<{}tender_vessel>,<{}test_mode>,<{}title>,<{}total_tare>,<{}transmission>,<{}transmit_date>,<{}transmit_log>,<{}transmit_log_time>,<{}transmit_type>,<{}trip_event_code>,<{}trip_event_def>,<{}trip_number>,<{}trip_number_verified>,<{}trip_wide>,<{}type_of_address>,<{}type_of_engine>,<{}type_of_generated_report>,<{}type_of_hull>,<{}type_of_landing_report>,<{}type_of_operation>,<{}type_of_owner>,<{}type_of_production_report>,<{}unit_name>,<{}unpublished>,<{}user_defined_alias>,<{}user_name>,<{}userid>,<{}valid_condition_code>,<{}value>,<{}version_label>,<{}version_number>,<{}vessel>,<{}vessel_defaults_source>,<{}vessel_name>,<{}waters>,<{}weight>,<{}weight_modifier>,<{}weight_modifier_def>,<{}weight_unit_of_measure>,<{}whole_mixed_salmon_average_weight>,<{}workstation_id>,<{}year>,<{}year_built>,<{}year_seq>,<{}zip_code>
at com.sun.xml.internal.bind.v2.runtime.unmarshaller.UnmarshallingContext.handleEvent(UnmarshallingContext.java:631)
at com.sun.xml.internal.bind.v2.runtime.unmarshaller.Loader.reportError(Loader.java:236)
at com.sun.xml.internal.bind.v2.runtime.unmarshaller.Loader.reportError(Loader.java:231)
at com.sun.xml.internal.bind.v2.runtime.unmarshaller.Loader.reportUnexpectedChildElement(Loader.java:105)

One way to correct this issue is to regenerate the landingreport.xsd generated files to a defined package like "landingreport". Then define this new path when creating an unmarshaller that points to "landingreport" subfolder as it's context when working with landingreport objects. Repeat this process for codes.xsd. Generated the codes.xsd files to the "codes" subfolder.

Alternatively you can generate the unmarshaller with something like:

JAXBContext jc = JAXBContext.newInstance(GENERATED_PACKAGE);
Unmarshaller u = jc.createUnmarshaller();

Schema schema = null;
SchemaFactory schemaFactory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
ClassLoader loader = Thread.currentThread().getContextClassLoader();
StreamSource[] sources;

sources = new StreamSource[4];
sources[0] = new StreamSource(loader.getResourceAsStream("datatypes.xsd"));
sources[1] = new StreamSource(loader.getResourceAsStream("dataelements.xsd"));
sources[2] = new StreamSource(loader.getResourceAsStream("codes.xsd"));
sources[3] = new StreamSource(loader.getResourceAsStream("landingreport.xsd"));

schema.newValidatorHandler();
u.setSchema(schema);