001    package org.bukkit;
002    
003    public interface TravelAgent {
004    
005        /**
006         * Set the Block radius to search in for available portals.
007         *
008         * @param radius The radius in which to search for a portal from the location.
009         * @return This travel agent.
010         */
011        public TravelAgent setSearchRadius(int radius);
012    
013        /**
014         * Gets the search radius value for finding an available portal.
015         *
016         * @return Returns the currently set search radius.
017         */
018        public int getSearchRadius();
019    
020        /**
021         * Sets the maximum radius from the given location to create a portal.
022         *
023         * @param radius The radius in which to create a portal from the location.
024         * @return This travel agent.
025         */
026        public TravelAgent setCreationRadius(int radius);
027    
028        /**
029         * Gets the maximum radius from the given location to create a portal.
030         *
031         * @return Returns the currently set creation radius.
032         */
033        public int getCreationRadius();
034    
035        /**
036         * Returns whether the TravelAgent will attempt to create a destination portal or not.
037         *
038         * @return Return whether the TravelAgent should create a destination portal or not.
039         */
040        public boolean getCanCreatePortal();
041    
042        /**
043         * Sets whether the TravelAgent should attempt to create a destination portal or not.
044         *
045         * @param create Sets whether the TravelAgent should create a destination portal or not.
046         */
047        public void setCanCreatePortal(boolean create);
048    
049        /**
050         * Attempt to find a portal near the given location, if a portal is not found it will attempt to create one.
051         *
052         * @param location The location where the search for a portal should begin.
053         * @return Returns the location of a portal which has been found or returns the location passed to the method if unsuccessful.
054         */
055        public Location findOrCreate(Location location);
056    
057        /**
058         * Attempt to find a portal near the given location.
059         *
060         * @param location The desired location of the portal.
061         * @return Returns the location of the nearest portal to the location.
062         */
063        public Location findPortal(Location location);
064    
065        /**
066         * Attempt to create a portal near the given location.
067         *
068         * @param location The desired location of the portal.
069         * @return True if a nether portal was successfully created.
070         */
071        public boolean createPortal(Location location);
072    }