001    package org.bukkit;
002    
003    /**
004     * The Travel Agent handles the creation and the research of Nether and End
005     * portals when Entities try to use one.
006     * <p>
007     * It is used in {@link org.bukkit.event.entity.EntityPortalEvent} and in
008     * {@link org.bukkit.event.player.PlayerPortalEvent} to help developers
009     * reproduce and/or modify Vanilla behaviour.
010     */
011    public interface TravelAgent {
012    
013        /**
014         * Set the Block radius to search in for available portals.
015         *
016         * @param radius the radius in which to search for a portal from the
017         *     location
018         * @return this travel agent
019         */
020        public TravelAgent setSearchRadius(int radius);
021    
022        /**
023         * Gets the search radius value for finding an available portal.
024         *
025         * @return the currently set search radius
026         */
027        public int getSearchRadius();
028    
029        /**
030         * Sets the maximum radius from the given location to create a portal.
031         *
032         * @param radius the radius in which to create a portal from the location
033         * @return this travel agent
034         */
035        public TravelAgent setCreationRadius(int radius);
036    
037        /**
038         * Gets the maximum radius from the given location to create a portal.
039         *
040         * @return the currently set creation radius
041         */
042        public int getCreationRadius();
043    
044        /**
045         * Returns whether the TravelAgent will attempt to create a destination
046         * portal or not.
047         *
048         * @return whether the TravelAgent should create a destination portal or
049         *     not
050         */
051        public boolean getCanCreatePortal();
052    
053        /**
054         * Sets whether the TravelAgent should attempt to create a destination
055         * portal or not.
056         *
057         * @param create Sets whether the TravelAgent should create a destination
058         *     portal or not
059         */
060        public void setCanCreatePortal(boolean create);
061    
062        /**
063         * Attempt to find a portal near the given location, if a portal is not
064         * found it will attempt to create one.
065         *
066         * @param location the location where the search for a portal should begin
067         * @return the location of a portal which has been found or returns the
068         *     location passed to the method if unsuccessful
069         * @see #createPortal(Location)
070         */
071        public Location findOrCreate(Location location);
072    
073        /**
074         * Attempt to find a portal near the given location.
075         *
076         * @param location the desired location of the portal
077         * @return the location of the nearest portal to the location
078         */
079        public Location findPortal(Location location);
080    
081        /**
082         * Attempt to create a portal near the given location.
083         * <p>
084         * In the case of a Nether portal teleportation, this will attempt to
085         * create a Nether portal.
086         * <p>
087         * In the case of an Ender portal teleportation, this will (re-)create the
088         * obsidian platform and clean blocks above it.
089         *
090         * @param location the desired location of the portal
091         * @return true if a portal was successfully created
092         */
093        public boolean createPortal(Location location);
094    }