org.ioc.commons.flowcontrol.placecontroller.PlaceController Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of ioc-commons Show documentation

This project defines a set of useful java interfaces for helping you in the definition of the structure of your developments in Java-projects which are designed using a Inversion-Of-Control (IOC) pattern. Useful for MVP-Pattern designs in applications coded on GWT, SWT, Android, etc.

There is a newer version: 1.2.1

Show newest version

package org.ioc.commons.flowcontrol.placecontroller;

import org.ioc.commons.flowcontrol.common.Params;
import org.ioc.commons.flowcontrol.eventbus.EventBusBinder;
import org.ioc.commons.flowcontrol.eventbus.IsEvent;

/**
 * Controller for leading the application to a determined place (generally, a
 * particular view associated to a place).
 * 
 * @author Jesús Lunar Pérez
 * 
 */
public interface PlaceController {
	public enum Event implements IsEvent {
		@Params({ IsPlace.class })
		PlaceChanged
	}

	/**
	 * Initializes the PlaceController.
	 * 
	 * A PlaceController needs to be initialized before using.
	 * 
	 * @param firstPlaceId
	 *            The first place where the application starts. A
	 *            #handleCurrentPlace() call just after this method is called,
	 *            will be equivalent to goTo(firstPlaceId).
	 * @param params
	 *            Parameters that will be sent along with the place.
	 */
	> void initPlaceController(P firstPlaceId, Object... params);

	/**
	 * Initializes the PlaceController and handle the current place now. It groups the
	 * calls to both {@link #initPlaceController(Enum, Object...)} and
	 * {@link #handleCurrentPlace()} in just one.
	 * 
	 * @param handleCurrentPlaceNow
	 *            true if after initialization the method
	 *            {@link #handleCurrentPlace()} will be called; false otherwise.
	 * @param firstPlaceId
	 *            First place where the controller must go in case there is no a
	 *            current place set.
	 * @param params
	 *            Parameters that will be sent along with the place.
	 */
	
> void initPlaceController(boolean handleCurrentPlaceNow, P firstPlaceId,
			Object... params);

	/**
	 * Leads the application to this place
	 * 
	 * @param placeId
	 *            Identifier for place where the application will go.
	 * @param params
	 *            Parameters that will be sent along with the place.
	 */
	
> void goTo(P placeId, Object... params);

	/**
	 * Leads the application to the place found into a {@link HasPlaceData}
	 * entity.
	 * 
	 * @param place
	 *            Place id container
	 */
	void goTo(HasPlaceData place);
	
	/**
	 * Leads the application to the previous place
	 */
	void goBack();

	/**
	 * Leads the application to the following place
	 */
	void goForward();

	/**
	 * Appends the place id found into a {@link HasPlaceData} in the history
	 * list.
	 * 
	 * @param place
	 *            Place id container
	 */
	void appendPlaceInHistory(HasPlaceData place);

	/**
	 * @return Info for the current place where the application is.
	 */
	HasPlaceData getCurrentPlaceData();

	/**
	 * Goes to the current place in case is not there yet.
	 */
	void handleCurrentPlace();

	/**
	 * Obtains a place data container for the passed parameters.
	 * 
	 * @param placeId
	 *            Place id
	 * @param params
	 *            Parameters for being sent along with the place id.
	 * 
	 * @return A place data information.
	 */
	
> HasPlaceData getPlaceData(P placeId, Object... params);

	/**
	 * Binder for the events which the place controller will fire
	 * 
	 * @return Event bus binder for the place controller events.
	 */
	EventBusBinder eventbus();

	/**
	 * 
	 * @return Gets the place registered as the first place
	 */
	HasPlaceData getFirstPlace();

	/**
	 * @return true if the current place is the first place; false otherwise
	 */
	boolean isCurrentPlaceFirstPlace();

	/**
	 * Implementations which can express current place as URL return it. Otherwise they must return an empty string. 
	 * 
	 * @return Current place as URL or empty string in case implementation is not able to return it.
	 */
	String currentPlaceAsUrl();

	/**
	 * Implementations which can express whichever place as URL return it. Otherwise they must return an empty string. 
	 * 
	 * @return Current place as URL or empty string in case implementation is not able to return it.
	 */
	> String getPlaceAsUrl(P placeId, Object... params);

	/**
	 * Implementations which can express whichever place as URL return it. Otherwise they must return an empty string. 
	 * 
	 * @return Current place as URL or empty string in case implementation is not able to return it.
	 */
	String getPlaceAsUrl(HasPlaceData placeData);
}