Developer's Guide > API Documentation > API Documentation PTV xLoad > Exceptions

Component xload

Diagrams

Exceptions

Enumerations

Service

Async

Input and Output

Operations

planZoneLoading

Plan the vehicle and load layout based on a two dimensional raster. The load consists of transport units of homogeneous size. Each transport unit has to be assigned to a specific zone in the loading space. These zones are composed of removable or movable wall elements and can require cooling units. Unplanned transport units are not supported. If the number of transport units increases the vehicle's loading space, the request fails.
Parameter Name Type Description
vehicleConfiguration VehicleConfiguration Configuration of the vehicle loading space (required).
transportUnits TransportUnit[] Potential transport units to load. If it is not possible to load all transport units, the units are selected randomly (required).
responseContents ResponseContents Options to configure the contents of the response (optional).
Return Type Description
ZoneLoadingPlan Plan that describes how to configure and load a multi zone vehicle.
XLoadException Thrown if an xLoad server exception such as an invalid request parameter occurs.
XServiceException Thrown if a PTV xServer framework exception occurs. 

startPlanZoneLoading

This is the asynchronous version of planZoneLoading. Calling this method will not block until the result has been calculated. Instead of a result object a Job object is returned which identifies the started calculation. To get status updates on a running job use the method watchJob and check the attribute status of type JobStatus. If it turns to SUCCEEDED, the calculation was successful and the result can be obtained using fetchZoneLoadingPlan. If the job ended with status FAILED, fetchZoneLoadingPlan throws the exception that occured during calculation.
Parameter Name Type Description
vehicleConfiguration VehicleConfiguration Configuration of the vehicle loading space (required).
transportUnits TransportUnit[] Potential transport units to load. If it is not possible to load all transport units, the units are selected randomly (required).
responseContents ResponseContents Options to configure the contents of the response (optional).
Return Type Description
Job The Job reference.
XLoadException Thrown if an xLoad server exception such as an invalid request parameter occurs.
XServiceException Thrown if a PTV xServer framework exception occurs. 

fetchZoneLoadingPlan

Fetches results of type ZoneLoadingPlan for the given job id. If the calculation ended with an exception fetchZoneLoadingPlan will rethrow it. If the id of the job is unknown a SystemException with message 'unknown id' is thrown.
Parameter Name Type Description
id String The id of the job.
Return Type Description
ZoneLoadingPlan Plan that describes how to configure and load a multi zone vehicle.
XLoadException Thrown if an xLoad server exception such as an invalid request parameter occurs.
XServiceException Thrown if a PTV xServer framework exception occurs. 

watchJob

Returns status information on jobs.
Parameter Name Type Description
id String The id of the job.
watchOptions WatchOptions The options to control job status and progress updates.
Return Type Description
Job The job reference.
SystemException Thrown if job management is not available, for example if it is misconfigured.

stopJob

Attempts to stop a running job. If the status of the job turns to SUCCEEDED, preliminary results can be fetched, if available.
Parameter Name Type Description
id String The id of the job to be stopped.
Return Type Description
Job The job reference.
SystemException Thrown if a preliminary result cannot be provided or job management in general is not available, for example if it is misconfigured.

deleteJob

Attempts to delete a running job. If successful the returned job will have state DELETED.
Parameter Name Type Description
id String The id of the job to be deleteed.
Return Type Description
Job The job reference.
SystemException Thrown if job management is not available, for example if it is misconfigured.

Classes

CoolingUnit

Representation of a cooling unit. A cooling unit does not occupy a storing position in the loading space.
Attribute Name Type Description
position Position Position of the cooling unit in the grid of storing positions. 0/0 is the front left corner in driving direction (required).

Position

Grid position in the loading space of the vehicle. There are two grids that describe the vehicle layout: a wall grid and a grid of storing positions. For the wall grid 0/0 represents an outside wall of the vehicle and is an invalid position for wall elements.
Attribute Name Type Description
row int Defines the position perpendicular to the driving direction.
column int Defines the position in driving direction.

ResponseContents

Options to configure the content of the response.
Attribute Name Type Description
vehicleLayout boolean If set to true, the layout of the vehicle walls is included in the response. The default value is true.
transportUnitAssignments boolean If set to true, the storing positions of the transport units are included in the response. The default value is true.

TransportUnit

Homogeneous item to load on a vehicle.
Attribute Name Type Description
id String Unique identifier of the transport unit. Duplicate identifiers cause an exception (required).
zoneId String Reference to the identifier of the zone that the transport unit should be assigned to (required).
stopIndexes int[] Stops where the transport unit or parts of the transport unit are unloaded. It is possible to unload a transport unit on multiple stops. The stops are considered to be visited in increasing order. For example, a transport unit for stop 0 should be unloaded before a transport unit for stop 1 (required).

TransportUnitAssignment

Assignment of a transport unit to a specific storing position in the loading space.
Attribute Name Type Description
transportUnitId String Reference to the unique identifier of the transportUnit to load.
position Position Position of the transport unit in the grid of storing positions. 0/0 is the front left corner in driving direction.

VehicleConfiguration

Configuration of the loading space. This area is described by two grids: the storing positions (red) and the wall grid (black). The grid of storing positions describes potential positions of transport units, the wall grid describes potential wall positions between the transport units. The exterior walls of the vehicle are invalid positions for wall elements.

The arrow indicates the direction of travel.

Attribute Name Type Description
numberOfColumns int Number of storing positions in driving direction.
numberOfRows int Number of storing positions perpendicular to the driving direction.
wallElements WallElement[] Wall elements that are available for the vehicle configuration. Removable wall elements may be ignored in the resulting vehicle layout (required).
coolingUnits CoolingUnit[] Cooling units that are available to refrigerate specific zones (optional).
zones Zone[] Zones that will be separated by walls in the resulting layout. For example zones for different temperatures (required).

VehicleLayout

The planned layout of vehicle walls.
Attribute Name Type Description
walls Wall[] The positioning of the wall elements. Unused wall elements are not returned.

Wall

The specific position of a wall element in the vehicle layout.
Attribute Name Type Description
orientation WallOrientation

Orientation of the wall.

startPosition Position Position of the wall element in the wall grid.
length int

Length of the wall measured in grid units.

WallElement

Static, removable or movable wall element to divide the loading space into zones.
Attribute Name Type Description
orientation WallOrientation Orientation type of the wall element.

The default value is ROW.

length int Length of the wall element measured in grid units.
wallStartPositionBounds WallPositionBounds Describes possible wall positions by defining a range of start positions (required).

Column walls have to start at a single point. That means minimumRow = maximumRow and minimumColumn=maximumColumn for column walls.

Row walls may only be moved in a specific column. That means minimumColumn = maximumColumn for row walls.

removable boolean Indicates that a wall element is removable and therefore optional. Removable wall elements do not have to be considered when planning.

The default value is false.

WallPositionBounds

Describes possible wall positions in the wall grid. Due to the fact that wall elements are not stretchable the bounds of the wall element are described by the starting position of the wall element relative to the origin of the wall grid.

Column walls have to start at a single point. That means minimumRow = maximumRow and minimumColumn=maximumColumn for column walls.

Row walls may only be moved in a specific column. That means minimumColumn = maximumColumn for row walls.

For example the red lines mark possible postions of a row wall with a length of one. The positions are labeled row / column.

Attribute Name Type Description
minimumColumn int Minimal start column of the wall element in the wall grid. 0/0 is the front left corner in driving direction.
maximumColumn int Maximum start column of the wall element in the wall grid. 0/0 is the front left corner in driving direction.

minimumRow int Minimal start row of the wall element in the wall grid. 0/0 is the front left corner in driving direction.
maximumRow int Maximum start row of the wall element in the wall grid. 0/0 is the front left corner in driving direction.

Zone

Zone in the loading space of the vehicle for a certain kind of goods. Zones are separated by wall elements.
Attribute Name Type Description
id String The unique identifier of the zone representing its characteristics. Duplicate identifiers will cause an exception (required).
requiresCoolingUnit boolean Indicates if a cooling unit is needed for this zone.

ZoneLoadingPlan

Output of the use case "load multi-zone vehicles". The composition of the response is configured using the ResponseContents object.
Attribute Name Type Description
vehicleLayout VehicleLayout Layout of the vehicle walls.
transportUnitAssignments TransportUnitAssignment[] Assignment of the planned transport units to storing positions in the loading space.

Enumerations

ErrorCode

Enumerator Name Value Description
LICENSE_ERROR 10000

License is not valid or expired.

REQUIREDPARAMETER_ERROR 10001

Missing a required input parameter.

INVALIDPARAMETER_ERROR 10002

A parameter was set to an invalid value.

MODULE_ERROR 10003

General error code of the xload module.

ENGINE_ERROR 10004

Engine call returned an error.

WallOrientation

Orientation type of a wall element.
Enumerator Name Value Description
ROW None Represents a wall oriented perpendicular to the driving direction.
COLUMN None Represents a wall oriented along the driving direction.

Exceptions

XLoadException

Thrown if an xLoad server exception such as an invalid request parameter occurs.

Component common

Diagrams

basetypes

opengis-geometry

Exceptions

Asynchronous Requests

Classes

BoundingBox

A bounding box, definded by its left top corner point and right bottom corner point.
Attribute Name Type Description
leftTop Point

The left top corner point.

rightBottom Point

The right bottom corner point.

BulkProgress

Extends JobProgress

Default implementation for bulk jobs.
Attribute Name Type Description
remaining int

Specifies how many requests have still to be calculated.

successful int

The number of successful calculations so far.

failed int

The number of failed computations so far.

ClusterProgress

Extends JobProgress

Implementation of JobProgress for cluster planning.
Attribute Name Type Description
action String

The current action being executed. For more information on progress see About Asynchronous Protocol.

distanceMatrixProgress DistanceMatrixProgress

The progress of the distance matrix calculation, available only if action equals "DistanceMatrix.Calculation".

optimizationProgress OptimizationProgress

The progress of the optimization, available only if action starts with "Optimization.".

DistanceMatrixCalculationProgress

Progress information of the currently active distance matrix calculation
Attribute Name Type Description
dimaId int

The unique key to identify the distance matrix currently being calculated.

currentDimaIndex int

The 1-based index of the distance matrix currently being calculated. Depending on the number of different vehicles in the request the number of distance matrices to be calculated can be greater than

lastDimaIndex int

The index of the last distance matrix to be calculated, that is the total number of distance matrices.

currentDistanceMatrixProgress DistanceMatrixProgress

The progress of the distance matrix currently being processed, available only if action equals "DistanceMatrix.Calculation".

DistanceMatrixProgress

Extends JobProgress

Default implementation for distance matrix calculation jobs.
Attribute Name Type Description
currentRowIndex int

The 1-based index of the current row of the current distance matrix being calculated.

lastRowIndex int

The index of the last row of the current distance matrix to be calculated.

EncodedGeometry

Extends EncodedGeometryBase

The abstract base class for geometry objects used in a geographical PTV xServer. Contains the attributes to represent openGIS conform encodings with a specific coordinate format. The actual representation is defined by the CallerContext ResponseGeometry property (GeometryEncoding) and the CallerContext CoordFormat property (CoordFormat).

Attribute Name Type Description
wkb byte[]

If not null, this attribute contains the well-known binary encoded form of the geometry

wkt String

If not null, this attribute contains the well-known text encoded form of the geometry

kml KML

If not null, this attribute contains the well-known text encoded form of the geometry

EncodedGeometryBase

The abstract base class for geometry objects.
No attributes defined.

GeometryCollection

Extends EncodedGeometry

A geometry collection as specified by the openGIS standard.
Attribute Name Type Description
geometryCollection PlainGeometryCollection

If not null, this attribute contains the explicit form of the geometry

ImprovementProgress

Progress information of the currently active improvement step of the optimization.
Attribute Name Type Description
availableMachineTime int

The available machine time stated in the request in [s]. This value is 0 if available machine time is not set in the request.

usedMachineTime int

The machine time already used in [s].

iterationIndex int

The index of this iteration. Index 0 denotes the initial plan directly after construction or the input plan.

numberOfImprovements int

The number of improvements the algorithm has already achieved. In other words, this is the number of tour plans with a smaller value of costOfObjectiveFunction than the best one at that time.

currentPlan KeyFigures

The key figures characterizing the current tour plan.

bestPlan KeyFigures

The key figures characterizing the currently best tour plan.

initialPlan KeyFigures

The key figures characterizing the initial tour plan. The initial tour plan is the input plan, if available, or the first tour plan after the construction step.

Job

Reference to jobs running in the background.
Attribute Name Type Description
id String

This id references the background job on the server.

status JobStatus

The current status of the job.

progress JobProgress

The current progress of the job. Can be null at the very beginning or very end of the request execution.

elapsedTime int

Elapsed time since this job has been queued.

JobProgress

Abstract base class for progresses. An individual PTV xServer might define its own implementations.
No attributes defined.

KML

Represents a KML geometry.
Attribute Name Type Description
kml String

The KML string itself.

placemarks String[]

The placemarks of the KML. If empty, all placemarks will be used. This will result in a GeometryCollection, if more than one exists.

KeyFigures

These key figures characterize a tour plan.
Attribute Name Type Description
costOfObjectiveFunction int

The optimization aims at minimizing the objective function. This value contains its arithmetical cost.

The significance of this value is not the value itself, but rather if and how fast it decreases during the calculation. The faster the value decreases the better the tour plans become according to the GoalImportance which defines what "better" means, at all.

numberOfScheduledOrders int

The number of orders already being scheduled.

numberOfUnscheduledOrders int

The number of orders not being scheduled, yet. These orders are feasible and can be scheduled during further improvement iterations.

numberOfInfeasibleOrders int

The number of orders not being scheduled. These orders are infeasible and will not be scheduled during further improvement iterations.

numberOfScheduledVehicles int

The number of vehicles being scheduled.

totalTourCount int

The number of all planned tours.

totalTourPeriod int

The sum of the tour periods for all planned tours ([sec]).

totalTourDrivingPeriod int

The sum of the tour driving periods for all planned tours ([sec]).

totalTourWaitingPeriod int

The sum of the tour waiting periods for all planned tours ([sec]).

totalTourDistance int

The sum of the tour distances for all planned tours ([m]).

totalTourCost int

The sum of the tour costs for all planned tours ([MU]). The costs per chain will not be included, see attribute totalChainCosts.

totalChainCost int

The sum of the costs per chain of all planned chains ([MU]). See VehicleCosts.

totalChainPeriod int

The sum of the chain periods of all planned chains ([sec]). The chain period is defined as the period between the start of the first tour and the end of the last tour. This period is greater than the sum of the periods of all tours if two subsequent tours do not start right after the other.

LineString

Extends EncodedGeometry

A line string as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
lineString PlainLineString

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

LinearRing

Extends EncodedGeometry

A linear ring as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
linearRing PlainLinearRing

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

MultiLineString

Extends EncodedGeometry

A multi line string as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
multiLineString PlainMultiLineString

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

MultiPoint

Extends EncodedGeometry

A multi point as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
multiPoint PlainMultiPoint

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

MultiPolygon

Extends EncodedGeometry

A multi polygon as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
multiPolygon PlainMultiPolygon

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

OptimizationProgress

The progress information of the currently active step of the optimization.
Attribute Name Type Description
currentLoopIndex int

The index of the current loop being calculated.

lastLoopIndex int

The index of the last loop being calculated. The calculation will automatically be finished by the algorithm before reaching this index when no improvement could be reached, anymore. The total number of loops can be set for the improvement step, only (see Params).

progress int

The progress in % of the current loop being calculated.

PlainGeometryBase

The abstract base class for the structured representation of geometry objects.
No attributes defined.

PlainGeometryCollection

Extends PlainGeometryBase

A plain structured polygon consisting of a set geometries.
Attribute Name Type Description
geometries PlainGeometryBase[]

The set of geometries making up the geometry collection.

PlainLineString

Extends PlainGeometryBase

A plain structured line string consisting of a set of points.

Attribute Name Type Description
points PlainPoint[]

The set of points defining the line string.

PlainLinearRing

Extends PlainGeometryBase

A plain structured linear ring consisting of a set of points

Attribute Name Type Description
points PlainPoint[]

The set of points defining the linear ring.

PlainMultiLineString

Extends PlainGeometryBase

A plain structured polygon consisting of a set of line strings.
Attribute Name Type Description
lineStrings PlainLineString[]

The set of line strings making up the multi line string.

PlainMultiPoint

Extends PlainGeometryBase

A plain structured polygon consisting of a set of points.
Attribute Name Type Description
points PlainPoint[]

The set of points making up the multi point.

PlainMultiPolygon

Extends PlainGeometryBase

A plain structured polygon consisting of a set of polygons.
Attribute Name Type Description
polygons PlainPolygon[]

The set of polygons making up the multi polygon.

PlainPoint

Extends PlainGeometryBase

A plain structured point consisting of two floating point attributes for the coordinates. In contrast to Point it is never transformed.

Attribute Name Type Description
x double

The x coordinate

y double

The y coordinate

z Double

The z coordinate (optional, only if requested)

PlainPolygon

Extends PlainGeometryBase

A plain structured polygon consisting of a set of linear rings.

Attribute Name Type Description
linearRings PlainLinearRing[]

The set of linear rings making up the polygon.

PlanProgress

Extends JobProgress

Implementation of JobProgress for tour planning.
Attribute Name Type Description
action String

The current action being executed. For more information on progress information see About Asynchronous Protocol.

distanceMatrixCalculationProgress DistanceMatrixCalculationProgress

The progress of the distance matrix calculation, available only if action starts with "DistanceMatrix.".

improvementProgress ImprovementProgress

The progress of the improvement step during the tour plan optimization, available only if action equals "Optimization.Improvement".

Point

Extends EncodedGeometry

Represents a single coordinate (point). Do not use this type for other points (e.g. pixel in an image), the coordinates are automatically transformed. Instead use PlainPoint.

See EncodedGeometry for possible representations.

Attribute Name Type Description
point PlainPoint

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

Polygon

Extends EncodedGeometry

A polygon as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
polygon PlainPolygon

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

RequestOptions

General options for requests

Attribute Name Type Description
coordFormat CoordFormat

The coordinate format used in the request/response.

responseGeometry GeometryEncoding[]

The geometry encoding for the response.

profile String

The name of the parameter profile to be used.

profileXMLSnippet String

For internal use only.

srId String

If the coordFormat equals to 'OG_SRID', this attribute contains the Spatial Reference Identifier as specified by the Open Geospatial Consortium (OGC), otherwise it is null. All codes of the EPSG Geodetic Parameter Dataset V7.9 maintained by the EPSG.

TerritoryProgress

Extends JobProgress

Implementation of JobProgress for territory planning.

Attribute Name Type Description
action String

The current action being executed. For more information on progress with territory planning see the use case documentation.

distanceMatrixProgress DistanceMatrixProgress

The progress of the distance matrix calculation, available only if action equals "DistanceMatrix.Calculation".

optimizationProgress int

The progress of the optimization, available only if action starts with "TerritoryOptimization.".

WatchOptions

This class includes options to control job status and progress updates. All parameters are optional.
Attribute Name Type Description
progressUpdatePeriod Integer

If defined this optional parameter enables additional progress updates with the specified interval. If no new progress update arrives during the specified period, watchJob will wait for and return with the next available progress update. Important updates such as terminal states will always return immediately. The minimum period must be at least 250ms. If no progress waiting period is defined, progress will only be sent as part of status updates.

maximumPollingPeriod Integer

Specifies the timeout after which watchJob will report the last status even if no further updates are available.If not specified a configured default is used.

ZoneLoadingProgress

Extends JobProgress

Attribute Name Type Description
action String

The current action being executed.

optimizationProgress int

The progress of the optimization, available only if action starts with "LoadingSpaceOptimization.".

Enumerations

CoordFormat

The CoordFormat enumeration contains all coordinate types supported by the PTV xServer. All examples represent the same geographic location.

Enumerator Name Value Description
OG_GEODECIMAL None

OpenGIS representation of WGS 84 coordinates. Example x=8.2505556, y=48.7627778.

PTV_MERCATOR None Mercator projection. Example x=917420, y=6227729.
PTV_GEOMINSEC None

PTV representation of coordinates by degree, minute, and second. Example x=815020, y=4845460.

PTV_GEODECIMAL None

PTV representation of WGS 84 coordinates. Example x=825056, y=4876278.

PTV_CONFORM None

PTV representation of conform coordinates. Example x=1672358, y=1620743.

PTV_SUPERCONFORM None

PTV representation of super-conform coordinates. Example x=5072358, y=3320743.

PTV_SMARTUNITS None

PTV internal coordinate format. Example x=4352286, y=5456405.

OG_SRID None

This format is set implicitly, if a Spatial Reference Identifier as specified by the Open Geospatial Consortium (OGC) is set in the CallerContext. All codes of the EPSG Geodetic Parameter Dataset V7.9 maintained by the EPSG..
Note: The coordinate format 'OG_GEODECIMAL' and the SRID code 'EPSG:4326' are equivalent.

ErrorCode

Enumerator Name Value Description
REQUEST_INVALID_WKT 10

The specified WKT in the request is invalid. It should a well-known text representation of a geometry from a string (see the OpenGIS simple features specification).

REQUEST_INVALID_WKB 11

The specified WKB in the request is invalid. It should be a geometry from a byte stream in well-known binary format.

REQUEST_INVALID_KML 12

The specified KML in the request is invalid.

KML_PLACEMARK_NOT_FOUND 13

Thrown, if requested placemark name is not found in the KML

CONVERT_GEOMETRY_OBJECT 20

One or more geometry objects in the request are invalid. There are problems to convert a geometry object to a plain geometry object. Also used for retrieving the plain geometry object from a geometry object.

CONVERT_COORDINATE_FORMAT 21

There are problems to convert a CoordFormat of the request to a coordinate type.

GEOMETRY_ENCODING 22

Geometry objects cannot be encoded.

GeometryEncoding

Defines encoding options for geometry parameters and results.

Plain indicates that geometry objects should be transmitted in plain object form, WKB indicates that openGIS well-known binary format should be used, WKT represents the openGIS well-known text format. KML represents the Keyhole Markup Language.

Enumerator Name Value Description
PLAIN None

Plain geometry encoding using structured objects and according network presentation.

WKB None

Geometry should be represented by well-known binaries.

WKT None

Use well-known texts to encode geometry objects.

KML None

Use Keyhole Markup Language to encode geometry objects.

JobStatus

Specifies different job status values.
Enumerator Name Value Description
QUEUING None

Job has been enqueued.

RUNNING None

Job is currently running.

STOPPING None

Stop has been requested, the job will terminate its calculation as soon as possible.

SUCCEEDED None

Job has completed successfully.

FAILED None

Job has failed with an exception.

DELETED None

The job was deleted by the user.

UNKNOWN None

The job is in an unknown state. For example a given id is unknown or the job has already been fetched and has thus been deleted from the underlying persistent store.

Exceptions

XServiceException

XServiceException is used for all exceptions which can occur in the PTV xServer framework.

SystemException (from package com.ptvag.jabba.core.exception)

This is the base class for all system relevant exceptions. It is thrown for example if a request has timed out or if a request has been rejected.