Skip to content

API_REFERENCE.md

Latest commit

 

History

History
493 lines (408 loc) · 13.8 KB

API_REFERENCE.md

File metadata and controls

493 lines (408 loc) · 13.8 KB

Railway Scheduling System - API Documentation

Quick Reference

Headers to Include

#include "Railwaysystem.h"  // All components
// OR include specific components:
#include "Station.h"
#include "Train.h"
#include "NotificationSystem.h"
#include "PassengerManagement.h"
#include "PerformanceAnalytics.h"
#include "RouteManager.h"
#include "DelayManagement.h"

Compilation

g++ -std=c++11 -Wall -Wextra -o your_app your_app.cpp src/*.cpp

Core Classes

Station Class

class Station {
public:
    // Constructors
    explicit Station(int id);               // Numeric ID
    explicit Station(const std::string& id); // String ID
    
    // Line Management
    void addLine(const std::string& lineName, int lineID, int platformNumber);
    std::vector<Line>& getLines();
    const std::vector<Line>& getLines() const;
    
    // Station Information
    std::string getStationID() const;
    
    // Validation
    static bool isStationIDUnique(const std::string& id);
    static bool isLineIDValid(int lineID);
    static bool isPlatformIDValid(int platformNumber);
};

Platform Class

class Platform {
public:
    explicit Platform(int number);
    
    // Scheduling
    bool addStoppage(std::time_t time);     // For stopping trains
    bool addThrough(std::time_t time);      // For through trains
    
    // Information
    int getPlatformNumber() const;
    const std::vector<std::pair<std::time_t, bool>>& getSchedule() const;
    
    // Utility
    static std::string timeToString(std::time_t time);
};

Train Hierarchy

// Abstract base class
class Train {
public:
    virtual ~Train() = default;
    
    // Pure virtual methods
    virtual double calculateTicketPrice(double distance) const = 0;
    virtual std::string getTrainType() const = 0;
    virtual int getStoppingTime() const = 0;
    virtual double getEffectiveSpeed() const = 0;
    
    // Common methods
    std::string getTrainNumber() const;
    std::string getTrainName() const;
    int getCapacity() const;
    double getBaseSpeed() const;
    virtual void displayTrainInfo() const;
};

// Concrete implementations
class ExpressTrain : public Train {
public:
    ExpressTrain(const std::string& number, const std::string& name, int cap = 500);
};

class LocalTrain : public Train {
public:
    LocalTrain(const std::string& number, const std::string& name, int cap = 800);
};

class HighSpeedTrain : public Train {
public:
    HighSpeedTrain(const std::string& number, const std::string& name, int cap = 300);
};

class FreightTrain : public Train {
public:
    FreightTrain(const std::string& number, const std::string& name, double weight);
    double getCargoWeight() const;
};

Scheduling System

Strategy Pattern

class SchedulingStrategy {
public:
    virtual ~SchedulingStrategy() = default;
    virtual bool scheduleTrains(Platform& platform, 
                              const std::vector<std::shared_ptr<Train>>& trains) = 0;
    virtual std::string getStrategyName() const = 0;
};

class FCFSScheduling : public SchedulingStrategy { /* ... */ };
class PriorityScheduling : public SchedulingStrategy { /* ... */ };
class OptimalScheduling : public SchedulingStrategy { /* ... */ };

class SchedulingContext {
public:
    SchedulingContext(std::unique_ptr<SchedulingStrategy> strat);
    void setStrategy(std::unique_ptr<SchedulingStrategy> strat);
    bool executeScheduling(Platform& platform, 
                          const std::vector<std::shared_ptr<Train>>& trains);
    std::string getCurrentStrategy() const;
};

Notification System

Observer Pattern

class Observer {
public:
    virtual ~Observer() = default;
    virtual void update(const std::string& message) = 0;
    virtual std::string getObserverType() const = 0;
};

class PassengerNotification : public Observer {
public:
    PassengerNotification(const std::string& id);
};

class StationMasterNotification : public Observer {
public:
    StationMasterNotification(const std::string& id);
};

class MaintenanceNotification : public Observer {
public:
    MaintenanceNotification();
};

class NotificationCenter {
public:
    void addObserver(std::shared_ptr<Observer> observer);
    void removeObserver(std::shared_ptr<Observer> observer);
    void notifyObservers(const std::string& message);
    
    // Specific notifications
    void notifyDelayUpdate(const std::string& trainNumber, int delayMinutes);
    void notifyPlatformChange(const std::string& trainNumber, int oldPlatform, int newPlatform);
    void notifyCancellation(const std::string& trainNumber, const std::string& reason);
    void notifyMaintenanceAlert(const std::string& platformOrTrack, const std::string& issue);
};

Passenger Management

Passenger & Ticket Classes

class Passenger {
public:
    Passenger(const std::string& id, const std::string& n, 
              const std::string& p, const std::string& e);
    
    std::string getPassengerID() const;
    std::string getName() const;
    std::string getPhone() const;
    std::string getEmail() const;
};

class Ticket {
public:
    enum class TicketStatus { BOOKED, CONFIRMED, CANCELLED, COMPLETED };
    enum class TicketClass { GENERAL, SLEEPER, AC_3_TIER, AC_2_TIER, AC_1_TIER };
    
    // Getters
    std::string getTicketID() const;
    std::string getPassengerID() const;
    std::string getTrainNumber() const;
    std::string getFromStation() const;
    std::string getToStation() const;
    std::time_t getJourneyDate() const;
    TicketClass getTicketClass() const;
    TicketStatus getStatus() const;
    double getPrice() const;
    int getSeatNumber() const;
    
    // Setters
    void setStatus(TicketStatus newStatus);
    void setSeatNumber(int seat);
    void setPrice(double newPrice);
    
    // Display
    void displayTicket() const;
    std::string getStatusString() const;
    std::string getClassString() const;
};

Pricing Strategies

class PricingStrategy {
public:
    virtual ~PricingStrategy() = default;
    virtual double calculatePrice(double basePrice, const Ticket& ticket) const = 0;
    virtual std::string getStrategyName() const = 0;
};

class RegularPricing : public PricingStrategy { /* ... */ };
class DynamicPricing : public PricingStrategy { /* ... */ };

Passenger Management System

class PassengerManagementSystem {
public:
    void setPricingStrategy(std::unique_ptr<PricingStrategy> strategy);
    
    // Passenger management
    bool registerPassenger(const std::string& id, const std::string& name, 
                          const std::string& phone, const std::string& email);
    std::shared_ptr<Passenger> findPassenger(const std::string& id);
    
    // Ticket management
    std::string bookTicket(const std::string& passengerID, const std::string& trainNumber,
                          const std::string& from, const std::string& to,
                          std::time_t journeyDate, Ticket::TicketClass ticketClass,
                          double basePrice);
    bool cancelTicket(const std::string& ticketID);
    bool confirmTicket(const std::string& ticketID);
    std::shared_ptr<Ticket> findTicket(const std::string& ticketID);
    
    // Analytics
    std::vector<std::shared_ptr<Ticket>> getPassengerTickets(const std::string& passengerID);
    int getTotalBookings() const;
    double getTotalRevenue() const;
    
    // Display
    void displayAllTickets() const;
    void displayPassengerBookings(const std::string& passengerID);
};

Performance Analytics

Singleton Pattern

class PerformanceAnalytics {
public:
    // Singleton access
    static PerformanceAnalytics* getInstance();
    
    // Data recording
    void recordDelay(const std::string& trainNumber, int delayMinutes);
    void recordStationTraffic(const std::string& stationID);
    void recordPlatformUtilization(const std::string& platformID, double utilizationPercent);
    void recordCancellation(const std::string& trainNumber);
    void recordRevenue(const std::string& routeName, double revenue);
    
    // Analytics
    double getAverageDelay(const std::string& trainNumber) const;
    double getSystemWideAverageDelay() const;
    std::string getMostDelayedTrain() const;
    std::string getBusiestStation() const;
    double getTotalRevenue() const;
    std::string getMostProfitableRoute() const;
    
    // Reports
    void generatePerformanceReport() const;
    void clearAllData();
};

Route Management

Composite Pattern

class RouteComponent {
public:
    virtual ~RouteComponent() = default;
    virtual double getTotalDistance() const = 0;
    virtual int getTotalStations() const = 0;
    virtual std::vector<std::string> getStationList() const = 0;
    virtual void displayRoute() const = 0;
    virtual std::string getRouteType() const = 0;
};

class RouteSegment : public RouteComponent {
public:
    RouteSegment(const std::string& from, const std::string& to, double dist);
    std::string getFromStation() const;
    std::string getToStation() const;
};

class CompleteRoute : public RouteComponent {
public:
    CompleteRoute(const std::string& name);
    void addSegment(std::shared_ptr<RouteComponent> segment);
    void removeSegment(std::shared_ptr<RouteComponent> segment);
    std::string getRouteName() const;
};

class RouteManager {
public:
    void addRoute(std::shared_ptr<CompleteRoute> route);
    void addDistance(const std::string& from, const std::string& to, double distance);
    std::shared_ptr<CompleteRoute> findRoute(const std::string& routeName);
    std::vector<std::string> findShortestPath(const std::string& start, const std::string& end);
    double calculateRouteDistance(const std::vector<std::string>& stations);
    void displayAllRoutes() const;
};

Delay Management

Delay Tracking

enum class DelayCategory {
    TECHNICAL_FAILURE,
    WEATHER,
    SIGNAL_PROBLEM,
    TRACK_MAINTENANCE,
    OVERCROWDING,
    EXTERNAL_FACTORS,
    OPERATIONAL_DELAY
};

class DelayIncident {
public:
    DelayIncident(const std::string& trainNum, DelayCategory cat, 
                 int delay, const std::string& desc);
    
    // Getters
    std::string getIncidentID() const;
    std::string getTrainNumber() const;
    DelayCategory getCategory() const;
    int getDelayMinutes() const;
    std::string getDescription() const;
    std::time_t getReportedTime() const;
    bool isResolved() const;
    
    // Operations
    void markResolved();
    void updateDelay(int newDelay);
    std::string getCategoryString() const;
    void displayIncident() const;
};

class DelayManagementSystem {
public:
    DelayManagementSystem(std::shared_ptr<NotificationCenter> nc = nullptr);
    void setNotificationCenter(std::shared_ptr<NotificationCenter> nc);
    
    // Delay operations
    std::string reportDelay(const std::string& trainNumber, DelayCategory category,
                           int delayMinutes, const std::string& description);
    bool updateDelay(const std::string& incidentID, int newDelayMinutes);
    bool resolveDelay(const std::string& incidentID);
    
    // Queries
    std::vector<std::shared_ptr<DelayIncident>> getTrainDelays(const std::string& trainNumber);
    std::vector<std::shared_ptr<DelayIncident>> getActiveDelays();
    
    // Analytics
    int getTotalDelayMinutes() const;
    double getAverageDelayTime() const;
    DelayCategory getMostCommonDelayCategory() const;
    std::string getMostDelayedTrain() const;
    
    // Display
    void displayActiveDelays() const;
    void displayDelayAnalytics() const;
};

Utility Functions

Time Helpers

// Create time from hours and minutes
std::time_t createTime(int hours, int minutes);

// Validate time
bool isValidTime(int hours, int minutes);

Error Handling

Exception Types

  • std::runtime_error: Operational errors (scheduling conflicts, invalid operations)
  • std::invalid_argument: Invalid parameters
  • std::out_of_range: Array/vector access errors

Example Error Handling

try {
    station.addLine("Test Line", 1, 1);
    platform.addStoppage(time);
} catch (const std::runtime_error& e) {
    std::cout << "Operation failed: " << e.what() << std::endl;
} catch (const std::exception& e) {
    std::cout << "General error: " << e.what() << std::endl;
}

Memory Management

Smart Pointers Usage

// Use shared_ptr for shared ownership
std::shared_ptr<Train> train = std::make_shared<ExpressTrain>("EXP001", "Express");

// Use unique_ptr for exclusive ownership
std::unique_ptr<SchedulingStrategy> strategy(new FCFSScheduling());

// For C++11 compatibility (no std::make_unique)
std::unique_ptr<PricingStrategy> pricing(new DynamicPricing());

RAII Principles

  • All resources are automatically managed
  • No manual memory deallocation required
  • Exception-safe design throughout

Best Practices

1. Always Check Return Values

std::string ticketID = pms.bookTicket(/* ... */);
if (!ticketID.empty()) {
    // Success
} else {
    // Handle failure
}

2. Use Exception Handling

try {
    platform.addStoppage(time);
} catch (const std::runtime_error& e) {
    // Handle scheduling conflict
}

3. Validate Input

if (Station::isStationIDUnique("NEW_STATION")) {
    stations.emplace_back("NEW_STATION");
}

4. Use Appropriate Design Patterns

// Strategy pattern for varying algorithms
scheduler.setStrategy(std::unique_ptr<SchedulingStrategy>(new PriorityScheduling()));

// Observer pattern for notifications
notificationCenter->addObserver(std::make_shared<PassengerNotification>("P001"));

// Singleton for global state
auto analytics = PerformanceAnalytics::getInstance();

Thread Safety Notes

  • Station ID management: Thread-safe (uses static containers)
  • Platform scheduling: Not thread-safe (implement your own locks)
  • Notification system: Not thread-safe
  • Analytics singleton: Not thread-safe for data modification

For multi-threaded applications, implement appropriate synchronization mechanisms.
⚡