Package net.sf.freecol.common.networking

Class ServerAPI

  • Direct Known Subclasses:
    AIServerAPI, UserServerAPI
    public abstract class ServerAPI
extends java.lang.Object
    The API for client/server messaging.

    • Field Detail

      • logger

        private static final java.util.logging.Logger logger

    • Constructor Detail

      • ServerAPI

        public ServerAPI()
        Creates a new ServerAPI.

    • Method Detail

      • connect

        public abstract Connection connect​(java.lang.String name,
                                   java.lang.String host,
                                   int port)
                            throws java.io.IOException
        Connects a client to host:port (or more).
        Parameters:
        name - The name for the thread.
        host - The name of the machine running the FreeColServer.
        port - The port to use when connecting to the host.
        Returns:
        True if the connection succeeded.
        Throws:
        java.io.IOException - on connection failure.

      • disconnect

        public abstract boolean disconnect()
        Disconnect from the server.
        Returns:
        True if disconnected.

      • reconnect

        public abstract Connection reconnect()
                              throws java.io.IOException
        Reconnect to the server.
        Returns:
        The reestablished Connection.
        Throws:
        java.io.IOException - on failure to connect.

      • getConnection

        public abstract Connection getConnection()
        Get the connection to communicate with the server.
        Returns:
        The Connection to the server.

      • setMessageHandler

        public void setMessageHandler​(MessageHandler mh)
        Sets the message handler for the connection.
        Parameters:
        mh - The new MessageHandler.

      • isConnected

        public boolean isConnected()
        Convenience utility to check the connection.
        Returns:
        True if the server connection is open.

      • check

        private Connection check​(java.lang.String operation,
                         java.lang.String type)
        Check the connection.
        Parameters:
        operation - The proposed operation.
        type - The proposed type of message.
        Returns:
        The Connection if valid, or null if not.

      • send

        private boolean send​(Message message)
        Sends a message to the server.
        Parameters:
        message - The Message to send.
        Returns:
        True if the send succeeded.

      • ask

        private boolean ask​(Message message)
        Sends the specified message to the server and processes the reply. In following routines we follow the convention that server I/O is confined to the askfoo() routine, which typically returns true if the server interaction succeeded, which does *not* necessarily imply that the actual substance of the request was allowed (e.g. a move may result in the death of a unit rather than actually moving).
        Parameters:
        message - A Message to send.
        Returns:
        True if the server interaction succeeded, that is, there was no I/O problem and the reply was not an error message.

      • abandonColony

        public boolean abandonColony​(Colony colony)
        Server query-response to abandon a colony.
        Parameters:
        colony - The Colony to abandon.
        Returns:
        True if the server interaction succeeded.

      • answerMonarch

        public boolean answerMonarch​(Monarch.MonarchAction action,
                             boolean accept)
        Server query-response to respond to a monarch offer.
        Parameters:
        action - The monarch action responded to.
        accept - Accept or reject the offer.
        Returns:
        True if the server interaction succeeded.

      • askSkill

        public boolean askSkill​(Unit unit,
                        Direction direction)
        Server query-response for finding out the skill taught at a settlement.
        Parameters:
        unit - The Unit that is asking.
        direction - The direction to a settlement to ask.
        Returns:
        True if the server interaction succeeded.

      • assignTeacher

        public boolean assignTeacher​(Unit student,
                             Unit teacher)
        Server query-response for assigning a teacher.
        Parameters:
        student - The student Unit.
        teacher - The teacher Unit.
        Returns:
        True if the server interaction succeeded.

      • assignTradeRoute

        public boolean assignTradeRoute​(Unit unit,
                                TradeRoute tradeRoute)
        Server query-response for assigning a trade route to a unit.
        Parameters:
        unit - The Unit to assign a trade route to.
        tradeRoute - The TradeRoute to assign.
        Returns:
        True if the server interaction succeeded.

      • attack

        public boolean attack​(Unit unit,
                      Direction direction)
        Server query-response for attacking.
        Parameters:
        unit - The Unit to perform the attack.
        direction - The direction in which to attack.
        Returns:
        True if the server interaction succeeded.

      • buildColony

        public boolean buildColony​(java.lang.String name,
                           Unit unit)
        Server query-response for building a colony.
        Parameters:
        name - The name for the colony.
        unit - The Unit that will build.
        Returns:
        True if the server interaction succeeded.

      • cashInTreasureTrain

        public boolean cashInTreasureTrain​(Unit unit)
        Server query-response to cash in a treasure train.
        Parameters:
        unit - The treasure train Unit to cash in.
        Returns:
        True if the server interaction succeeded.

      • changeState

        public boolean changeState​(Unit unit,
                           Unit.UnitState state)
        Server query-response for changing unit state.
        Parameters:
        unit - The Unit to change the state of.
        state - The new UnitState.
        Returns:
        boolean true if the server interaction succeeded.

      • changeWorkImprovementType

        public boolean changeWorkImprovementType​(Unit unit,
                                         TileImprovementType type)
        Server query-response for changing work improvement type.
        Parameters:
        unit - The Unit to change the work type of.
        type - The new TileImprovementType to work on.
        Returns:
        True if the server interaction succeeded.

      • changeWorkType

        public boolean changeWorkType​(Unit unit,
                              GoodsType workType)
        Server query-response for changing work type.
        Parameters:
        unit - The Unit to change the work type of.
        workType - The new GoodsType to produce.
        Returns:
        True if the server interaction succeeded.

      • chat

        public boolean chat​(Player player,
                    java.lang.String chat)
        Send a chat message (pre and in-game).
        Parameters:
        player - The Player to chat to.
        chat - The text of the message.
        Returns:
        True if the send succeeded.

      • chooseFoundingFather

        public boolean chooseFoundingFather​(java.util.List<FoundingFather> ffs,
                                    FoundingFather ff)
        Send a chooseFoundingFather message.
        Parameters:
        ffs - A list of FoundingFathers to choose from.
        ff - The chosen FoundingFather (may be null).
        Returns:
        True if the send succeeded.

      • claimTile

        public boolean claimTile​(Tile tile,
                         FreeColGameObject claimant,
                         int price)
        Server query-response to claim a tile.
        Parameters:
        tile - The Tile to claim.
        claimant - The Unit or Settlement that is claiming the tile.
        price - The amount to pay.
        Returns:
        True if the server interaction succeeded.

      • clearSpeciality

        public boolean clearSpeciality​(Unit unit)
        Server query-response for clearing a unit speciality.
        Parameters:
        unit - The Unit to operate on.
        Returns:
        True if the server interaction succeeded.

      • continuePlaying

        public boolean continuePlaying()
        Server query-response to continue with a won game.
        Returns:
        True if the server interaction succeeded.

      • declareIndependence

        public boolean declareIndependence​(java.lang.String nation,
                                   java.lang.String country)
        Server query-response for declaring independence.
        Parameters:
        nation - The name for the new nation.
        country - The name for the new country.
        Returns:
        True if the server interaction succeeded.

      • declineMounds

        public boolean declineMounds​(Unit unit,
                             Direction direction)
        Server query-response for the special case of deciding to explore a rumour but then declining not to investigate the strange mounds.
        Parameters:
        unit - The Unit that is exploring.
        direction - The Direction to move.
        Returns:
        True if the server interaction succeeded.

      • deleteTradeRoute

        public boolean deleteTradeRoute​(TradeRoute tradeRoute)
        Server query-response for deleting a trade route.
        Parameters:
        tradeRoute - The TradeRoute to delete.
        Returns:
        True if the server interaction succeeded.

      • deliverGiftToSettlement

        public boolean deliverGiftToSettlement​(Unit unit,
                                       IndianSettlement is,
                                       Goods goods)
        Server query-response to give the given goods to the natives.
        Parameters:
        unit - The Unit that is trading.
        is - The IndianSettlement that is trading.
        goods - The Goods to give.
        Returns:
        True if the server interaction succeeded.

      • demandTribute

        public boolean demandTribute​(Unit unit,
                             Direction direction)
        Server query-response for demanding a tribute from a native settlement.
        Parameters:
        unit - The Unit that demands.
        direction - The direction to demand in.
        Returns:
        True if the server interaction succeeded.

      • diplomacy

        public boolean diplomacy​(FreeColGameObject our,
                         FreeColGameObject other,
                         DiplomaticTrade dt)
        Handler server query-response for diplomatic messages.
        Parameters:
        our - Our object (Unit or Colony) conducting the diplomacy.
        other - The other object (Unit or Colony) to negotiate with.
        dt - The DiplomaticTrade agreement to propose.
        Returns:
        The resulting agreement or null if none present.

      • disbandUnit

        public boolean disbandUnit​(Unit unit)
        Server query-response for disbanding a unit.
        Parameters:
        unit - The Unit to operate on.
        Returns:
        True if the server interaction succeeded.

      • disembark

        public boolean disembark​(Unit unit)
        Server query-response for disembarking from a carrier.
        Parameters:
        unit - The Unit that is disembarking.
        Returns:
        True if the server interaction succeeded.

      • embark

        public boolean embark​(Unit unit,
                      Unit carrier,
                      Direction direction)
        Server query-response for boarding a carrier.
        Parameters:
        unit - The Unit that is boarding.
        carrier - The carrier Unit.
        direction - An optional direction if the unit is boarding from an adjacent tile, or null if from the same tile.
        Returns:
        True if the server interaction succeeded.

      • emigrate

        public boolean emigrate​(int slot)
        Server query-response for emigration.
        Parameters:
        slot - The slot from which the unit migrates, 1-3 selects a specific one, otherwise the server will choose one.
        Returns:
        True if the client-server interaction succeeded.

      • endTurn

        public boolean endTurn()
        Server query-response for asking for the turn to end.
        Returns:
        True if the server interaction succeeded.

      • enterRevengeMode

        public boolean enterRevengeMode()
        Server query-response for asking to enter revenge mode (post-game).
        Returns:
        True if the server interaction succeeded.

      • equipUnitForRole

        public boolean equipUnitForRole​(Unit unit,
                                Role role,
                                int roleCount)
        Server query-response for equipping a unit for a role.
        Parameters:
        unit - The Unit to equip.
        role - The Role to assume.
        roleCount - The role count.
        Returns:
        True if the server interaction succeeded.

      • firstContact

        public boolean firstContact​(Player player,
                            Player other,
                            Tile tile,
                            boolean result)
        Server query-response for responding to a first contact message.
        Parameters:
        player - The Player making contact.
        other - The native Player being contacted.
        tile - An optional Tile to offer the player if they have made a first landing.
        result - Whether the initial peace treaty was accepted.
        Returns:
        True if the server interaction succeeded.

      • getHighScores

        public boolean getHighScores​(java.lang.String key)
        Server query-response for asking for the high scores list.
        Parameters:
        key - The high score key to query.
        Returns:
        True if the server interaction succeeded.

      • nationSummary

        public boolean nationSummary​(Player self,
                             Player player)
        Server query-response for asking for the nation summary of a player.
        Parameters:
        self - The Player requesting the summary.
        player - The Player to summarize.
        Returns:
        True if the server interaction succeeded.

      • incite

        public boolean incite​(Unit unit,
                      IndianSettlement is,
                      Player enemy,
                      int gold)
        Server query-response for inciting the natives.
        Parameters:
        unit - The missionary Unit.
        is - The IndianSettlement to incite.
        enemy - An enemy Player.
        gold - The amount of bribe, negative to enquire.
        Returns:
        True if the server interaction succeeded.

      • indianDemand

        public boolean indianDemand​(Unit unit,
                            Colony colony,
                            GoodsType type,
                            int amount,
                            Constants.IndianDemandAction result)
        Makes demands to a colony. One and only one of goods or gold is valid.
        Parameters:
        unit - The Unit that is demanding.
        colony - The Colony to demand of.
        type - The GoodsType to demand.
        amount - The amount of goods to demand.
        result - The result of the demand.
        Returns:
        True if the server interaction succeeded.

      • joinColony

        public boolean joinColony​(Unit unit,
                          Colony colony)
        Server query-response for joining a colony.
        Parameters:
        unit - The Unit that will join.
        colony - The Colony to join.
        Returns:
        True if the server interaction succeeded.

      • learnSkill

        public boolean learnSkill​(Unit unit,
                          Direction direction)
        Server query-response for learning the skill taught at a settlement.
        Parameters:
        unit - The Unit that is asking.
        direction - The direction to a settlement to ask.
        Returns:
        True if the server interaction succeeded.

      • loadGoods

        public boolean loadGoods​(Location loc,
                         GoodsType type,
                         int amount,
                         Unit carrier)
        Server query-response for loading goods.
        Parameters:
        loc - The Location where the goods are.
        type - The GoodsType to load.
        amount - The amount of goods to load.
        carrier - The Unit to load onto.
        Returns:
        True if the server interaction succeeded.

      • login

        public boolean login​(java.lang.String userName,
                     java.lang.String version,
                     boolean single,
                     boolean current)
        Server query-response for logging in a player (pre-game).
        Parameters:
        userName - The user name.
        version - The client version.
        single - True if this is a single player login.
        current - True if the requesting player should become the current player.
        Returns:
        True if the server interaction succeeded.

      • logout

        public boolean logout​(Player player,
                      Game.LogoutReason reason)
        Server query-response for logging out.
        Parameters:
        player - The Player that has logged out.
        reason - The reason for logging out.
        Returns:
        True if the server interaction succeeded.

      • loot

        public boolean loot​(Unit winner,
                    java.lang.String defenderId,
                    java.util.List<Goods> goods)
        Server query-response for looting. Handles both an initial query and the actual looting.
        Parameters:
        winner - The Unit that is looting.
        defenderId - The identifier of the defender unit (it may have sunk).
        goods - A list of Goods, if empty this is a query as to what is to be looted which is filled into the list, if non-empty, then the list of goods to loot.
        Returns:
        True if the server interaction succeeded.

      • missionary

        public boolean missionary​(Unit unit,
                          Direction direction,
                          boolean denounce)
        Server query-response for establishing/denouncing a mission.
        Parameters:
        unit - The missionary Unit.
        direction - The direction to a settlement to establish with.
        denounce - True if this is a denouncement.
        Returns:
        True if the server interaction succeeded.

      • move

        public boolean move​(Unit unit,
                    Direction direction)
        Server query-response for moving a unit.
        Parameters:
        unit - The Unit to move.
        direction - The direction to move in.
        Returns:
        True if the server interaction succeeded.

      • moveTo

        public boolean moveTo​(Unit unit,
                      Location destination)
        Server query-response for moving to across the high seas.
        Parameters:
        unit - The Unit to move.
        destination - The Location to move to.
        Returns:
        True if the server interaction succeeded.

      • nativeGift

        public boolean nativeGift​(Unit unit,
                          Colony colony)
        A native Unit delivers the gift it is carrying to a colony.
        Parameters:
        unit - The Unit delivering the gift.
        colony - The Colony to give to.
        Returns:
        True if the server interaction succeeded.

      • newLandName

        public boolean newLandName​(Unit unit,
                           java.lang.String name)
        Server query-response for naming a new land.
        Parameters:
        unit - The Unit that has come ashore.
        name - The new land name.
        Returns:
        True if the server interaction succeeded.

      • nativeTrade

        public boolean nativeTrade​(NativeTrade.NativeTradeAction action,
                           NativeTrade nt)
        Server query-response for simple native trades.
        Parameters:
        nt - The NativeTrade underway.
        action - The NativeTradeAction to perform.
        Returns:
        True if the server interaction succeeded.

      • newNativeTradeSession

        public boolean newNativeTradeSession​(Unit unit,
                                     IndianSettlement is)
        Server query-response to get the session for a trade.
        Parameters:
        unit - The Unit that is trading.
        is - The IndianSettlement that is trading.
        Returns:
        True if the server interaction succeeded.

      • newRegionName

        public boolean newRegionName​(Region region,
                             Tile tile,
                             Unit unit,
                             java.lang.String name)
        Server query-response for naming a new region.
        Parameters:
        region - The Region that is being discovered.
        tile - The Tile where the region is discovered.
        unit - The Unit discovering the region.
        name - The new region name.
        Returns:
        True if the server interaction succeeded.

      • newTradeRoute

        public boolean newTradeRoute()
        Server query-response for creating a new trade route.
        Returns:
        True if the server interaction succeeded.

      • payArrears

        public boolean payArrears​(GoodsType type)
        Server query-response for tax paying arrears.
        Parameters:
        type - The GoodsType to pay the arrears for.
        Returns:
        True if the server interaction succeeded.

      • payForBuilding

        public boolean payForBuilding​(Colony colony)
        Server query-response for paying for a building.
        Parameters:
        colony - The Colony that is building.
        Returns:
        True if the server interaction succeeded.

      • putOutsideColony

        public boolean putOutsideColony​(Unit unit)
        Server query-response for putting a unit outside a colony.
        Parameters:
        unit - The Unit to put out.
        Returns:
        True if the server interaction succeeded.

      • rearrangeColony

        public boolean rearrangeColony​(Colony colony,
                               java.util.List<Unit> workers,
                               Colony scratch)
        Rearrange a colony.
        Parameters:
        colony - The Colony to rearrange.
        workers - A list of worker Units that may change.
        scratch - A copy of the underlying Colony with the workers arranged as required.
        Returns:
        True if the server interaction succeeds.

      • rename

        public boolean rename​(FreeColGameObject object,
                      java.lang.String name)
        Server query-response for renaming an object.
        Parameters:
        object - A FreeColGameObject to rename.
        name - The name to apply.
        Returns:
        True if the server interaction succeeded.

      • requestLaunch

        public boolean requestLaunch()
        Server query-response to launch the game (pre-game).
        Returns:
        True if the server interaction succeeded.

      • retire

        public boolean retire()
        Server query-response to retire the player from the game.
        Returns:
        True if the server interaction succeeded.

      • scoutSettlement

        public boolean scoutSettlement​(Unit unit,
                               Direction direction)
        Server query-response for the dialog on scouting a native settlement, *before* choosing to speak to the chief, attack, et al.
        Parameters:
        unit - The Unit that is speaking.
        direction - The direction to a settlement to ask.
        Returns:
        True if the server interaction succeeded.

      • scoutSpeakToChief

        public boolean scoutSpeakToChief​(Unit unit,
                                 IndianSettlement is)
        Server query-response for speaking with a native chief.
        Parameters:
        unit - The Unit that is speaking.
        is - The IndianSettlement to ask.
        Returns:
        True if the server interaction succeeded.

      • setAvailable

        public boolean setAvailable​(Nation nation,
                            NationOptions.NationState state)
        Server query-response to set a nation's availablility (pre-game).
        Parameters:
        nation - The Nation to whose availability is to be set.
        state - The NationState defining the availability.
        Returns:
        True if the server interaction succeeded.

      • setBuildQueue

        public boolean setBuildQueue​(Colony colony,
                             java.util.List<BuildableType> buildQueue)
        Server query-response for changing a build queue.
        Parameters:
        colony - the Colony
        buildQueue - the new values for the build queue
        Returns:
        True if the server interaction succeeded.

      • setColor

        public boolean setColor​(Nation nation,
                        java.awt.Color color)
        Server query-response to set a nation colour (pre-game).
        Parameters:
        nation - The Nation to set the color for.
        color - The Color selected.
        Returns:
        True if the server interaction succeeded.

      • setCurrentStop

        public boolean setCurrentStop​(Unit unit,
                              int index)
        Server query-response to set the current stop.
        Parameters:
        unit - The Unit whose stop is to be updated.
        index - The stop index.
        Returns:
        True if the query-response succeeds.

      • setDestination

        public boolean setDestination​(Unit unit,
                              Location destination)
        Server query-response to set the destination of the given unit.
        Parameters:
        unit - The Unit to direct.
        destination - The destination Location.
        Returns:
        True if the server interaction succeeded.
        See Also:
        Unit.setDestination(Location)

      • setGoodsLevels

        public boolean setGoodsLevels​(Colony colony,
                              ExportData data)
        Server query-response for setting goods levels.
        Parameters:
        colony - The Colony where the levels are set.
        data - The ExportData setting.
        Returns:
        True if the server interaction succeeded.

      • setNation

        public boolean setNation​(Nation nation)
        Server query-response to show which nation a player has selected (pre-game).
        Parameters:
        nation - The Nation selected.
        Returns:
        True if the server interaction succeeded.

      • setNationType

        public boolean setNationType​(NationType nationType)
        Server query-response to show which nation type a player has selected (pre-game).
        Parameters:
        nationType - The NationType selected.
        Returns:
        True if the server interaction succeeded.

      • setReady

        public boolean setReady​(boolean ready)
        Server query-response for indicating that this player is ready (pre-game).
        Parameters:
        ready - The readiness state to signal.
        Returns:
        True if the server interaction succeeded.

      • spy

        public boolean spy​(Unit unit,
                   Settlement settlement)
        Server query-response for spying on a colony.
        Parameters:
        unit - The Unit that is spying.
        settlement - The Settlement to spy on.
        Returns:
        True if the client/server interaction succeeded.

      • startSkipping

        public boolean startSkipping()
        Server query-response for starting to skip turns.
        Returns:
        True if the server interaction succeeded.

      • trainUnitInEurope

        public boolean trainUnitInEurope​(UnitType type)
        Server query-response for training a unit in Europe.
        Parameters:
        type - The UnitType to train.
        Returns:
        True if the server interaction succeeded.

      • unloadGoods

        public boolean unloadGoods​(GoodsType type,
                           int amount,
                           Unit carrier)
        Server query-response for unloading goods.
        Parameters:
        type - The GoodsType to unload.
        amount - The amount of goods to unload.
        carrier - The Unit to unload from.
        Returns:
        True if the query-response succeeds.

      • updateGameOptions

        public boolean updateGameOptions​(OptionGroup gameOptions)
        Server query-response to update the game options (pre-game).
        Parameters:
        gameOptions - The OptionGroup containing the game options.
        Returns:
        True if the server interaction succeeded.

      • updateMapGeneratorOptions

        public boolean updateMapGeneratorOptions​(OptionGroup mapOptions)
        Server query-response to update the map generator options (pre-game).
        Parameters:
        mapOptions - The OptionGroup containing the map generator options.
        Returns:
        True if the server interaction succeeded.

      • updateTradeRoute

        public boolean updateTradeRoute​(TradeRoute route)
        Server query-response for asking for updating the trade route.
        Parameters:
        route - The trade route to update.
        Returns:
        True if the server interaction succeeded.

      • work

        public boolean work​(Unit unit,
                    WorkLocation workLocation)
        Server query-response for changing a work location.
        Parameters:
        unit - The Unit to change the workLocation of.
        workLocation - The WorkLocation to change to.
        Returns:
        True if the server interaction succeeded.