Monitors {@link PlaceChangeEvent}s and {@link com.google.gwt.user.client.History} events and keep them in sync.

class PlaceHistoryHandler {
//  private static final Logger log = Logger.getLogger(PlaceHistoryHandler.class.getName());

 Historian _historian;

 PlaceHistoryMapper _mapper;

 PlaceController _placeController;

 Place _defaultPlace = Place.NOWHERE;

 /**
  * Create a new PlaceHistoryHandler.
  * 
  * @param mapper a {@link PlaceHistoryMapper} instance
  * @param historian a {@link Historian} instance
  */
 PlaceHistoryHandler(this._mapper, [Historian historian = null]) {
   if (historian == null) {
     _historian = new DefaultHistorian();
   } else {
     _historian = historian;
   }
 }

 /**
  * Handle the current history token. Typically called at application start, to
  * ensure bookmark launches work.
  */
 void handleCurrentHistory() {
   _handleHistoryToken(_historian.getToken());
 }

//  /**
//   * Legacy method tied to the old location for {@link EventBus}.
//   * 
//   * @deprecated use {@link #register(PlaceController, EventBus, Place)}
//   */
//  @Deprecated
//  com.google.gwt.event.shared.HandlerRegistration register(PlaceController placeController,
//      com.google.gwt.event.shared.EventBus eventBus, Place defaultPlace) {
//    return new LegacyHandlerWrapper(register(placeController, (EventBus) eventBus, defaultPlace));
//  }

 /**
  * Initialize this place history handler.
  * 
  * @return a registration object to de-register the handler
  */
 HandlerRegistration register(PlaceController placeController, EventBus eventBus,
     Place defaultPlace) {
   this._placeController = placeController;
   this._defaultPlace = defaultPlace;

   
   HandlerRegistration placeReg =
       eventBus.addHandler(PlaceChangeEvent.TYPE, new _PlaceChangeEventHandlerAdapter(this)); 

   HandlerRegistration historyReg =
       _historian.addValueChangeHandler(new ValueChangeHandlerAdapter<String>((ValueChangeEvent<String> event) {
         String token = event.value;
         _handleHistoryToken(token);
       }));

   return new _PlaceHistoryHandlerRegistration(this, placeReg, historyReg);
 }

//  /**
//   * Visible for testing.
//   */
//  Logger log() {
//    return log;
//  }

 void _handleHistoryToken(String token) {

   Place newPlace = null;

   if ("" == token) {
     newPlace = _defaultPlace;
   }

   if (newPlace == null) {
     newPlace = _mapper.getPlace(token);
   }

   if (newPlace == null) {
//      log().warning("Unrecognized history token: " + token);
     newPlace = _defaultPlace;
   }

   _placeController.goTo(newPlace);
 }

 String _tokenForPlace(Place newPlace) {
   if (_defaultPlace == newPlace) {
     return "";
   }

   String token = _mapper.getToken(newPlace);
   if (token != null) {
     return token;
   }

//    log().warning("Place not mapped to a token: " + newPlace);
   return "";
 }
}