Table of contents

General information

History of changes

Abbreviations

Project terminology

Bibliography

Document purpose

Total system

Scope of services

Restrictions

Components and component relations

Web interface

Calling servlets

Servlet requests and responses

Servlets and Messages (Overview)

Booking servlets

BookingServlet

AmendServlet

AvailabilityServlet

DisplayServlet

InformationServlet

Base data servlets

LoginServlet

ServiceListServlet

ServiceDetailsServlet

ServiceGroupsServlet

ServiceDatesServlet

Compression of xml messages

Error codes coming from Mellow server

Errors during database query

Errors during marshaling/validation of xml messages

Errors during login

Errors during request for service list

Errors during request for a service group

Errors during request for service details

Outstanding questions

General information

History of changes

Abbreviations

Project terminology

Bibliography

Document purpose

The present document describes the Mellow web interface that provides an interface for booking operations and base data requests to the Ocean tour operator system via internet. Data between an external system, as for example a web client, and the web interface is exchanged in messages in the OceanTravel xml format that is well documented in the OceanTravel.html document.

The following chapters describe scopes and restrictions of the Mellow web interface, the different components of the system and their collaboration. Chapter contains a detailed specification of the servlets provided by the Mellow web interface.

Total system

Scope of services

The functional range of the Mellow web interface can be divided into two parts, functionality for handling booking requests and functionality for handling requests for base data stored in the Ocean database.

The web interface can manage booking actions as for example booking requests, amend requests, elementary availability requests, requests for a specific PNR or requests about service provider specific information stored in the Ocean database.

A web client using the Mellow web interface can also readout some base data from the Ocean database, for example a list containing all services that can be booked by an external system. For every service, details can be retrieved as there are dates, service categories and the package structure of a service package.

Restrictions

The Mellow web interface does not support all kinds of messages defined in the OceanTravel.xsd schema. All supported message types are described in more detail in chapter .

Components and component relations

The Mellow web interface consists of two main parts, the Mellow servlets and the Mellow server, where the servlets provide the real interface for an external system as for example a web client.

The following diagram shows the communication between a web client, the Mellow web interface, and the Ocean booking server respectively the Ocean database.

Every request to the web interface is handled by the Mellow servlets. Each servlet provides functionality for handling a predefined request type.

The Mellow server handles the connections to the Ocean database and to the Ocean booking server. It receives requests from the Mellow servlets and does either forward them to the booking server or execute a query for base data in the Ocean database. As the Mellow server is - viewed from the outside - a hidden part of the web interface, it is not described in detail in the present document.

Web interface

The Mellow servlets are divided into two groups, the booking servlets and the base data servlets. Each servlet extends the MellowServlet that itself is derived from the javax.servlet.HttpServlet. The hierarchy of the Mellow servlets is shown in the class diagram below.

Calling servlets

A servlet in common is called via its URL. The URL for a servlet has the following general form depending on which server is used to run the servlets. The following example assumes that Tomcat is used as servlet runner, as Tomcat is the standard servlet engine we recommend to use with the Mellow web interface.

https://machine-name:port/Context-root/Servlet-name

If the IP address of the PC Tomcat is running on is 127.0.0.1 and the port is 8080, and the Mellow servlets are deployed in TOMCAT_HOME/webapps/mellow/WEB-INF/classes the Mellow login servlet would be called as follows:

https://127.0.0.1:8080/mellow/servlet/LoginServlet

Servlet requests and responses

Every Mellow servlet does implement the doPost(HttpServletRequest req, HttpServletResponse resp) method. So a request to a servlet is to be sent by the HTTP POST method. A Mellow servlet expects two strings coming with one request. The first string has to be a flag, indicating if the proper xml request is compressed or not. That flag is not optional and has to be a string with the value true or false. The second string contains the booking data and can be compressed or not. The Mellow web interface does also provide functionality for packing request strings.

The following section shows an example implementation of how a Mellow servlet can be called:

URLConnection connection;

String flag = false; //Flag if the string containing the xml request is

compressed or not.

String xmlRequest; //String containing the xml request data.

Serializable[] data = new Serializable[2]; // Array containing the data

// to write to servlet

data[0] = flag;

data[1] = xmlRequest;

connection = servletURL.openConnection();

ObjectOutputStream out;

// Stream to write the request for the servlet to

out = new ObjectOutputStream( connection.getOutputStream() );

// First, write the compression flag

out.writeObject( data[0] );

// Second, write the xml request string

out.writeObject( data[1] );

out.flush();

out.close();

// Stream to read the servlet response from

ObjectInputStream in =

new ObjectInputStream( connection.getInputStream() );

byte[] xmlResponse = ( (String)in.readObject() ).getBytes();

// Decode the response string using UTF-8 encoding

String strResponse = new String( xmlResponse, UTF-8 );

In.close();

The servlets response is written to its output stream in the same order as the request. The servlet also writes two strings, first the compression flag, second the packed or not packed xml response.

Servlets and Messages (Overview)

As mentioned above, the Servlets can be divided in booking and base data servlets. It depends on the message, which Servlet to use. The following list shows all available messages and the corresponding Servlet. Messages processed by a base data servlet are passed through Mellow and sent to the booking server, that holds application functionality.

Please regard, that the functionality of these messages depends strongly on the particular tour operator system.

Booking servlets

Every Mellow servlet handles one of the message types specified in the OceanTravel.html document. In the following the Mellow servlets are described with the message types they can handle and with some examples for illustration.

BookingServlet

The BookingServlet handles any OceanMsg containing a BookingRQ as defined in the OceanTravel.html document. Booking requests cover all messages with the action codes Book, BookConfirm, BookPending, BookQuery, OnRequest, Option, OptionConfirm, OptionQuery and Reservation. The following xml message is an example of a minimal booking request that can be sent to the BookingServlet. The specification of the BookingRQ and BookingRS message type can be found in the OceanTravel.html document.

<OceanMsg>

<BookingRQ Action Book'>

<POS>

<ConsultantName>Meier</ConsultantName>

<AgencyKey>555</ AgencyKey >

<OfficeKey>100</ OfficeKey >

<TerminalKey>100</ TerminalKey >

</POS>

<Customer>

<FirstName>John</FirstName>

<LastName>Smith</LastName>

<Street>Berliner Strae 99</Street>

<PostalCode> </PostalCode>

<City>Frankfurt am Main</City>

<Country>GER</Country>

</Customer>

<ServiceList>

<Service RPH '>

<ServiceType>F</ServiceType>

<ServiceCode>BERMUC3</ServiceCode>

<ServiceCategory>C</ServiceCategory>

<FromDate> </FromDate>

<Duration> </Duration>

</Service>

</ServiceList>

<NumberOfTravelers> </NumberOfTravelers>

<TravelerList>

<Traveler RPH '>

<ModeOfAddress>H</ModeOfAddress>

<LastName>Smith</LastName>

</Traveler>

</TravelerList>

<Remarks>This is a test booking only.</Remarks>

</BookingRQ>

</OceanMsg>

A response message for that booking request can look as follows:

<OceanMsg>

<BookingRS>

<Success/>

<BookingData>

<POS>

<ConsultantName>Meier</ConsultantName>

<AgencyKey>555</ AgencyKey >

<OfficeKey>100</ OfficeKey >

<TerminalKey>100</ TerminalKey >

</POS>

<ServiceList>

<Service RPH '>

<ServiceType>F</ServiceType>

<ServiceCode>BERMUC3</ServiceCode>

<ServiceCategory>C</ServiceCategory>

<FromDate> </FromDate>

<EndDate> </EndDate>

</Service>

</ServiceList>

<NumberOfTravelers> </NumberOfTravelers>

<TravelerList>

<Traveler RPH '>

<ModeOfAddress>H</ModeOfAddress>

<LastName>Smith</LastName>

</Traveler>

</TravelerList>

</BookingData>

<ServiceStateList>

<ServiceState ServiceRPH '>OK</ServiceState>

</ServiceStateList>

<PriceData Currency AED'>

<ServicePriceList>

<ServicePrice ServiceRPH '> </ServicePrice>

</ServicePriceList>

<TravelerPriceList>

<TravelerPrice TravelerRPH '> </TravelerPrice>

</TravelerPriceList>

<TotalPrice Currency AED'> </TotalPrice>

</PriceData>

</BookingRS>

</OceanMsg>

AmendServlet

The AmendServlet handles every AmendRQ as defined in the OceanTravel.html document. Amend requests cover the actions Cancel, CancelQuery, FirmBooking, FirmReservation, Rebook, RebookQuery, RebookOption and RebookReservation. An amend request may look as follows:

<OceanMsg>

<AmendRQ Action Cancel'>

<POS>

<ConsultantName>Meier</ConsultantName>

<AgencyKey>555</ AgencyKey >

<OfficeKey>100</ OfficeKey >

<TerminalKey>100</ TerminalKey >

</POS>

<Reservation>

<Id>587</Id>

<Version> </Version>

</Reservation>

<ServiceList>

<Service RPH '>

<ServiceType>F</ServiceType>

<ServiceCode>BERMUC3</ServiceCode>

<ServiceCategory>C</ServiceCategory>

<FromDate> </FromDate>

<EndDate> </EndDate>

</Service>

</ServiceList>

<TravelerList Group String'>

<Traveler RPH '>

<ModeOfAddress>H</ModeOfAddress>

<LastName>Smith</LastName>

</Traveler>

</TravelerList>

</AmendRQ>

</OceanMsg>

The AmendRQ and AmendRS message types are defined in the OceanTravel.html document.

AvailabilityServlet

The AvailabilityServlet handles messages containing the AvailabilityRQ type, and sends back AvailabilityRS messages. Action codes covered by that servlet are Hotel and Transport. If the availability should return only free units this can be controlled with the OnlyFreeUnits flag in the AvailabilityRQ tag. The request and response message structures for that servlet are defined in OceanTravel.html as AvailabilityRQ and AvailabilityRS element.

Example for an AvailabilityRQ:

<?xml version='1.0' encoding='UTF-8'?>

<!--Sample XML file generated by XML Spy v4.0 U (https://www.xmlspy.com)-->

<OceanMsg>

<AvailabilityRQ Action Hotel Language en OnlyFreeUnits '>

<ServiceProvider>PROV</ServiceProvider>

<ServiceType>H</ServiceType>

<BrochureCode>SUMMER03</BrochureCode>

<ServiceCode>ALA0101</ServiceCode>

<ServiceCategory>S</ServiceCategory>

<POS>

<ConsultantName>Tester</ConsultantName>

<AgencyKey> </AgencyKey>

<OfficeKey> </OfficeKey>

</POS>

<FromDate> </FromDate>

<EndDate> </EndDate>

<NumberOfTravelers> </NumberOfTravelers>

</AvailabilityRQ>

</OceanMsg>

Example for an AvailabilityRS:

<OceanMsg>

<AvailabilityRS Language en'>

<Success/>

<ServiceProvider>PROV</ServiceProvider>

<POS>

<ConsultantName>Tester</ConsultantName>

<AgencyKey> </AgencyKey>

<OfficeKey> </OfficeKey>

</POS>

<ResultList>

<Result ID OccupancyMin OccupancyMax OccupancyDef DaysOfArrival BrochurePage

MinimumStay ServiceDesc Nice hotel ChildMin BabyMin '>

<ServiceType>H</ServiceType>

<BrochureCode>SUMMER03</BrochureCode>

<ServiceCode>ALA0101</ServiceCode>

<ServiceCategory>S</ServiceCategory>

<AvailabilityList>

<Availability Date '> </Availability>

<Availability Date '> </Availability>

<Availability Date '> </Availability>

<Availability Date '> </Availability>

<Availability Date '> </Availability>

</AvailabilityList>

</Result>

</ResultList>

</AvailabilityRS>

</OceanMsg>

DisplayServlet

The DisplayServlet receives requests containing information about a PNR and sends back the corresponding PNR, so that it can be displayed by a web client. A display request does not contain any action and may look like the example below:

<OceanMsg>

<DisplayRQ>

<ServiceProvider>ISO</ServiceProvider>

<POS>

<ConsultantName>Meier</ConsultantName>

<AgencyKey> </AgencyKey>

<OfficeKey> </OfficeKey>

<TerminalKey> </TerminalKey>

</POS>

<Reservation>

<Id> </Id>

<Version> </Version>

</Reservation>

</DisplayRQ>

</OceanMsg>

For a detailed description of the DisplayRQ and DisplayRS message please refer to the definition of that message types in the OceanTravel.html document.

InformationServlet

A service provider can make available specific information about itself in the Ocean database. That information can be requested using the InformationServlet. The example below shows an information request:

<OceanMsg>

<InfoRQ>

<ServiceProvider>ISO</ServiceProvider>

<POS>

<ConsultantName>Meier</ConsultantName>

<AgencyKey> </AgencyKey>

<OfficeKey> </OfficeKey>

<TerminalKey> </TerminalKey>

</POS>

</InfoRQ>

</OceanMsg>

The response for that request contains a list with information lines, containing the service provider specific information stored in the database.

<OceanMsg>

<InfoRS>

<Success/>

<InfoLines>

<InfoLine>Line one containing service provider information</InfoLine>

<InfoLine>Line two containing service provider specific information</InfoLine>

</InfoLines>

</InfoRS>

</OceanMsg>

Base data servlets

The detailed specification of the message types handled by the base data servlets can also be found in the OceanTravel.html document.

LoginServlet

For a login at the tour operator system a web client has to send a user name, which is in our case the user id of the booking agency, and a password to the Mellow web interface. How users for Mellow are created is described in detail in the Mellow installation guidelines, section 2.9.2. The message below shows an example login request sent to the LoginServlet:

<OceanMsg>

<LoginRQ>

<Name> </Name>

<Password>webuser</Password>

</LoginRQ>

</OceanMsg>

If the login with the given data is successful, the agency information for that customer is read out of the database and sent back to the web client. That data has to be used as PointOfSale for all following requests to the web interface. The response for the example request above would look as follows:

<OceanMsg>

<LoginRS>

<Success/>

<User>

<Name> </Name>

<AgencyKey> </AgencyKey>

<OfficeKey> </OfficeKey>

<TerminalKey> </TerminalKey>

</User>

</LoginRS>

</OceanMsg>

ServiceListServlet

The ServiceListServlet sends back a list containing all services that can be booked by external systems. For each service the service type, the brochure code, the service code, the region, the short description and the description is in that list.

A ServiceListRQ contains only the ServiceProvider and optionally a language key, so that descriptions and short descriptions can be sent back in the language requested by the web client, on the condition that the corresponding translations are stored in the database. If not, the descriptions are sent back in the systems default language. The language argument is a valid ISO Language Code. These codes are the lower-case, two-letter codes as defined by ISO-639. A full list with of these codes can be found at the following web address https://www.ics.uci.edu/pub/ietf/http/related/iso639.txt.

Below you see an example for a service list request:

<OceanMsg>

<ServiceListRQ Language en'>

<ServiceProvider>ISO</ServiceProvider>

</ServiceListRQ>

</OceanMsg>

A response message containing a service list may look as follows:

<OceanMsg>

<ServiceListRS>

<Success/>

<ServiceList>

<ServiceSpec>

<ServiceType>H</ServiceType>

<BrochureCode>SUMMER02</BrochureCode>

<ServiceCode>ALA010</ServiceCode>

<Region>BARUMI</Region>

<ShortDescription Language en'>Hotel test</ShortDescription>

<DetailedDescription Language en'>Nice hotel in the south of BARUMI</DetailedDescription>

</ServiceSpec>

<ServiceSpec>

<ServiceType>P</ServiceType>

<BrochureCode> SUMMER02</BrochureCode>

<ServiceCode>TRIPBAR</ServiceCode>

<ProformaType>T</ProformaType>

<Region>BARUMI</Region>

<ShortDescription Language en'>Round trip</ShortDescription>

<DetailedDescription Language en'>Roud trip through BARUMI</DetailedDescription>

</ServiceSpec>

</ServiceList>

</ServiceListRS>

</OceanMsg>

ServiceDetailsServlet

With the ServiceDetailsServlet categories for a single service can be requested from the Ocean database. Therefore the ServiceDetailRQ contains those details of a service that enable a unique assignment. The language attribute is optional and is sent for the same reason as described in the section above:

<OceanMsg>

<ServiceDetailRQ Language en'>

<ServiceType>H</ServiceType>

<BrochureCode> SUMMER02</BrochureCode>

<ServiceCode> ALA010</ServiceCode>

</ServiceDetailRQ>

</OceanMsg>

For the requested service all categories that can be sold externally are sent back with their min, max and normal occupancy and their short description.

<OceanMsg>

<ServiceDetailRS>

<Success/>

<ServiceSpec>

<ServiceType>H</ServiceType>

<BrochureCode> SUMMER02</BrochureCode>

<ServiceCode>ALA010</ServiceCode>

<Categories>

<Category>

<CategoryCode>S</CategoryCode>

<MinOccupancy> </MinOccupancy>

<MaxOccupancy> </MaxOccupancy>

<NormalOccupancy>1</NormalOccupancy>

<OvernightKey> </OvernightKey>

<ShortDescription Language en'>Single room</ShortDescription>

</Category>

<Category>

<CategoryCode>D</CategoryCode>

<MinOccupancy> </MinOccupancy>

<MaxOccupancy> </MaxOccupancy>

<NormalOccupancy>2</NormalOccupancy>

<OvernightKey> </OvernightKey>

<ShortDescription Language en'>Double room</ShortDescription>

</Category>

</Categories>

</ServiceSpec>

</ServiceDetailRS>

</OceanMsg>

ServiceGroupsServlet

With the ServiceGroupsServlet all services associated to a service package can be requested. Therefore a similar request as for service details has to be sent to the web interface.

The following example shows a request for a service group:

<OceanMsg>

<ServiceGroupsRQ Language en'>

<ServiceType>P</ServiceType>

<BrochureCode>SUMMER02</BrochureCode>

<ServiceCode>TRIPBAR</ServiceCode>

</ServiceGroupsRQ>

</OceanMsg>

As the response for a ServiceGroupsRQ would take too much place here, an example can be found in the ServiceGroupsRSExample.xml file attached to the present document.

For a detailed specification of the ServiceGroupsRQ and ServiceGroupsRS type please refer to the OceanTravel.html document.

ServiceDatesServlet

For every service booking dates can be requested from the Ocean database with the ServiceDatesServlet. The request for service dates is similar to the other base data requests. The service category is optional but makes sense in the most cases, as dates are usually stored for the singular categories of a service.

<OceanMsg>

<ServiceDatesRQ Language en'>

<ServiceType>H</ServiceType>

<BrochureCode>SUMMER02</BrochureCode>

<ServiceCode>ALA010</ServiceCode>

<ServiceCategory></ServiceCategory>

</ServiceDatesRQ>

</OceanMsg>

The dates response does not contain the service details any more, but only a list with dates:

<OceanMsg>

<ServiceDatesRS>

<Dates Category TimeFrame'>

<Date>

<ArriveDepart>Arrival</ArriveDepart>

<Date>2003-01-01</Date>

<MinPeriod>7</MinPeriod>

<Interval>7</Interval>

</Date>

<Date>

<ArriveDepart>Departure</ArriveDepart>

<Date>2003-01-08</Date>

</Date>

</Dates>

</ServiceDatesRS>

</OceanMsg>

Please note: This list does not contain all possible booking dates of a service. Those dates have to be calculated with the information contained in that list. Therefore the web interface does provide functionality for calculation of all possible booking dates with the data contained in the ServiceDatesRS message.

Compression of xml messages

For the compression and decompression of xml requests and responses the Mellow B2C web interface provides the class DataCompression in the package de.isogmbh.io.zip

For compression of a xml string, the string has first to be converted into a byte array with the method public byte[] getBytes() in the java.lang.String class and can then be compressed calling the method

public static byte[] compressByteArray(byte[] bArrInput)

of the DataCompression class. This method returns the compressed byte array that can be converted into a string again and be sent to a servlet.

The decompression of a xml string is made by converting the string into byte array again, and then by calling the method

public static byte[] decompressByteArray(byte[] bArrInput).

That method again returns the decompressed byte array.

Both methods throw a java.io.IOException if something happens during compression or decompression.

Error codes coming from Mellow server

The Mellow server sends back error codes with the response message, every time an error occurs during a request for a base data with one of the following servlets:

LoginServlet

ServiceListServlet

ServiceDetailServlet

ServiceGroupsServlet

ServiceDatesServlet

If a booking request fails in the XML server, a NullPointerException is thrown.

In the following section all possible error codes and their meanings are described: Each error code is a negative number between -100 and -999. The error codes are sent back in the error structure defined in the OceanTravel.html document. The following example shows the error section of an OceanTravel xml message containing error codes:

<OceanMsg>

..

<Errors>

<Error Code '/>

<Error Code -303'/ >

</Errors>

..

</OceanMsg>

Errors during database query

: Connection to database lost

: Error during execution of database query

: No result set was found or error in result set

Errors during marshaling/validation of xml messages

All xml messages coming to the Mellow server are validated and unmarshaled with the Castor framework. If an error occurs during unmarshaling a xml message, a default response message is created with one of the following error codes:

: Error during unmarshaling xml message. In that case, a corrupted xml message came to the Mellow server.

: Error during validating xml message. Mostly in that case, a mandatory field is missing in the message coming to the Mellow server.

: Other exceptions during unmarshaling message.

The following sections describe those errors that can occur additional to the database and validation errors in the specific base data requests.

Errors during login

: There was no user data sent with the request message.

: The user is not allowed to connect to database. In that case, the user name an/or password sent to the Mellow server was not correct.

Errors during request for service list

: The xml request sent to the Mellow server did not contain a request for a service list.

: The service provider given in the xml request is not the service provider the Mellow server works for.

: Neither the requested service list file nor the default service list file can be found on the server. In that case either the path to the service list files on the Mellow server is not correct or the service list files have not yet been generated.

Errors during request for a service group

: The xml message sent to the Mellow server does not contain a request for a service group. In that case a wrong request was sent to the Mellow server.

Errors during request for service details

: The xml message sent to the Mellow server does not contain a request for service details. In that case a wrong request was sent to the Mellow server.

Outstanding questions