net.sf.eBus.client.EObject Maven / Gradle / Ivy
//
// Copyright 2016 Charles W. Rapp
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
package net.sf.eBus.client;
/**
* This interface solves the problem of start up and shutting
* down from a non-eBus thread. When an application object is
* opening feeds, it is possible that eBus will call the object
* back before the object's start up method is completed.
* Synchronization must then be used to prevent start up
* interruption. But synchronization should not be necessary
* due to eBus guaranteeing that it will access clients in a
* single-threaded fashion.
*
* The solution is to have an eBus dispatcher thread trigger the
* object start up and shutdown methods. While the object is
* opening feeds, any and all callbacks triggered by the feed
* opening will not be posted until after the start up method
* returns.
*
*
* A similar issue exists with shutting down application objects
* from a non-eBus thread: after a feed is closed, the feed may
* still deliver messages to the application object. Shutting
* down feeds from an eBus thread removes this issue since all
* the object's pending message queue will be cleared.
*
*
* An application can either override these methods or
* provide a {@link Runnable} lambda expression as the start up
* and/or shutdown methods to
* {@link EFeed#register(EObject, String)}.
*
*
* @author Charles Rapp
*/
public interface EObject
{
//---------------------------------------------------------------
// Member data.
//
//-----------------------------------------------------------
// Constants.
//
/**
* Default eBus object name is {@value}.
*/
public static final String NAME_NOT_SET = "(not set)";
//---------------------------------------------------------------
// Member methods.
//
/**
* Returns eBus object name. Provided for application
* purposes only and not used by eBus. Defaults to
* {@link #NAME_NOT_SET}.
* @return eBus object name.
*/
default String name()
{
return (NAME_NOT_SET);
} // end of name()
/**
* {@link EFeed#startup(EObject)} calls this method to
* asynchronously start up an eBus client from an eBus
* thread. This means that object start up processing will
* not be interrupted by an eBus callback.
*
* The default implementation does nothing. This method can
* be "overridden" using a {@link Runnable} interface
* implementation.
*
*
* @see #shutdown()
*/
default void startup()
{}
/**
* {@link EFeed#shutdown(EObject)} calls this method to
* asynchronously shutdown an eBus client from an eBus
* thread. This means that object shutdown processing will
* not be interrupted by an eBus callback.
*
* Note: having eBus shutdown an application
* object results in all open eBus feeds associated
* with that application object being closed. It is not
* possible to partially shutdown the object's feeds. The
* eBus shutdown functionality should be used only when the
* object is no longer needed.
*
*
* The default implementation does nothing. This method can
* be "overridden" using a {@link Runnable} interface
* implementation.
*
*
* @see #startup()
*/
default void shutdown()
{}
} // end of interface EObject