|
server.idl |
//Background of the project:
//Assumptions:
//1. The world is in two dimensions, and the position definition follows
// the normal coordination that (0,0) is the left-bottom corner.
//2. Each plane is assigned to an unique id when they are served by the
// the Server.
module ServerModule {
//
//This structure holds the brief position information of the plane:
// long id: the id of the plane
// float x: the x_position of the plane
// float y: the y_position of the plane
struct PlanePosition_Brief {
long id;
float x;
float y;
};
//This structure holds the position information of the plane:
// long id: the id of the plane
// float x: the x_position of the plane
// float y: the y_position of the plane
// float vx: the x_velocity of the plane (could be negative value)
// float vy: the y_velocity of the plane (could be negative value)
struct PlanePosition_Detail{
long id;
float x;
float y;
float vx;
float vy;
};
//define the type of array of PlanePosition_Brief
typedef sequence <PlanePosition_Brief> PositionInfo_Brief;
//define the type of array of PlanePosition_Detail
typedef sequence <PlanePosition_Detail> PositionInfo_Detail;
//The exception when the client passed in invalid plane id
exception invalid_plane_id{};
exception invalid_coordinate{} ;
exception system_overload{};
//Category: Baseline
//Behavior: This interface supports methods to simulate the functions
// of a GroundAirTrafficControlCenter.
//Inherits from: NONE
//Clients: Planes
interface TrafficControl {
//Category: Baseline
//Behavior:
// 1. The client is supposed to call this function every 2s to
// update their position.
// 2. If this call returns exceptions, the client should retry
// to update his position to another Server
//Parameters:
// long id: the id of the plane
// float x: the x_position of the plane
// float y: the y_position of the plane
// float vx: the x_velocity of the plane (could be negative value)
// float vy: the y_velocity of the plane (could be negative value)
//Return Value:
// the name of the ground tower
//Exceptions: invalid_plane_id, invalid_coordinate
//Clients: Planes
string PositionUpdate(in long id, in float x, in float y, in float vx, in float vy)
raises (invalid_plane_id, invalid_coordinate);
//Category: Baseline
//Behavior:
// 1. When the client joins the system we will assign him a unique id.
// 2. Low priority call, no real time deadline
// Assumptions:
// 1. Clients only make this call once.
//Parameters:
// long id: the id of the plane
//Return Value:
// no return value
//Exceptions: None
//
//Clients: Planes
long Join(in string name) raises (system_overload);
//Category: Baseline
//Behavior:
// 1. When the plane leaves our system we should remove
// him from the our control and remove his id.
// 2. Client ignores the exception on duplicate submission.
// 3. Low priority call, no real time deadline
//Parameters:
// long id: the id of the plane
//Return Value:
// true if success
//Exceptions:
// 1. invalid_plane_id
//Clients: Planes
boolean Leave(in long id) raises (invalid_plane_id);
//Category: Baseline
//Behavior:
// 1. The client is supposed to call this function every 20s to
// inquiry about all planes which are at a distance of less
// than radius1
// 2. The value of this radius is determined by the plane. For
// different types of planes, this value can be different.
// 3. If this call returns exceptions, the client should switch
// to another Server right away.
// 4. The client should calculate if there are any planes which
// are "dangerous" (within a distance of less than radius2),it
// will start to call EmergencyInquery to get more information
// about these planes.
// 5. This call has lower priority than EmergencyInquery calls.
// 6. The Server should return in 20s, even without actual
// information. In this case, the client will switch to
// EmergencyInquery.
//Parameters:
// long id: the id of the plane
// float x: the x_position of the plane
// float y: the y_position of the plane
// long radius1:
//Return Value:
// The array with plane positions, please refer to Behavior for
// details.
//Exceptions:
// 1. invalid_plane_id
// 2. invalid_coordinate
//Clients: Planes
PositionInfo_Brief Inquiry(in long id,in float x, in float y, in float radius1)
raises (invalid_plane_id,invalid_coordinate,system_overload);
//Category: Baseline
//Behavior:
// 1. When any other plane is in a "dangerous" radius2 (please
// refer to Inquiry) or this plane has just switched to another
// Server, the client is supposed to call this function every
// 10s to inquire about all planes which are at a distance of less
// than radius2
// 2. The value of radius2 is determined by the plane. For
// different types of planes, this value can be different.
// 3. If this call returns exceptions, the client should switch
// to another Server right away.
// 4. The client should calculate if there is no plane in
// radius2 based on information returned, it should call
// Inquiry from now on.
// 5. This call has higher priority than Inquiry calls.
//Parameters:
// long id: the id of the plane
// float x: the x_Position of the plane
// float y: the y_Position of the plane
// long radius2:
//Return Value:
// Return the array with plane positions and their velocity information.
//Exceptions:
// 1. invalid_plane_id
// 2. invalid_coordinate
//Clients: Planes
PositionInfo_Detail EmergencyInquiry(in long id,in float x, in float y, in float radius2)
raises (invalid_plane_id, invalid_coordinate);
//%TODO: add comments
boolean is_alive();
boolean become_primary();
};
//Category: Reliability
//Behavior:
//Inherits from: None
//Clients: Servers, both types Primary and Backup
interface Backup {
//Category: Reliability
//Behavior:
// 1. The primary Server should call this function at Backup Server
// to synchronize the planes' position information.
// 2. This is a one way operation; the primary Server will not
// retry this operation in case of failure for any reason
// because the information will become outdate after 2s.
// 3. If this call returns exceptions, the Backup Server is down.
//Parameters:
// long id: the id of the plane
// float x: the x_Position of the plane
// float y: the y_Position of the plane
// float vx: the x_velocity of the plane (could be negative value)
// float vy: the y_velocity of the plane (could be negative value)
//Return Value:
// no return value, success if no system exception was thrown.
//Exceptions:
//
//Clients: Primary Server
oneway void PositionBackup(in long id, in float x, in float y, in float vx, in float vy);
//Category: Reliability
//Behavior:
// 1. When the primary Server receive a Join() request, it will
// pass this call to Backup Server. Only after the two servers
// have performed the Join(), the plane client could continue.
// This could simplify the fail over process.
// 2. If this call returns exceptions, the Backup Server is down.
//Assumptions:
// 1. Assuming Network Reliability, this is called only once for every Join.
//Parameters:
// none
//Return Value:
// True if Success , False otherwise
//Exceptions:
//
//Clients: Primary Server
boolean JoinSync();
//Category: Reliability
//Behavior:
// 1. When the primary Server receives a Leave() request, it will
// pass this call to the Backup Server. Only after two servers have
// performed the Leave(), the plane client could continue.
// This could simplify the fail over process.
// 2. If this call returns system exceptions, it implies that the Backup Server is down.
// 3. The Server ignores invalid_plane_id exception.
//Parameters:
// long id: the id of the plane
//Return Value:
// true if success
//Exceptions: invalid_plane_id
//Clients: Primary Server
boolean LeaveSync(in long id) raises (invalid_plane_id);
//TODO: It is necessary to add some interface to support the fail over
// process. Maybe the Heartbeat protocol should be implemented.
// This issue is under technical investigation.
};
};
|
server.idl |