net.sf.eBus.client.ESingleFeed Maven / Gradle / Ivy
The newest version!
//
// Copyright 2018, 2020 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;
import java.util.Objects;
import net.sf.eBus.messages.EMessageKey;
import net.sf.eBus.util.Validator;
/**
* Base class for all feeds which connect to a single
* {@link ESubject eBus subject}.
*
* @author Charles W. Rapp
*/
/* package */ abstract class ESingleFeed
extends EFeed
{
//---------------------------------------------------------------
// Enums.
//
/**
* Enumerates the supported feed types. There are four basic
* feed types:
*
* -
* publishing notification messages,
*
* -
* receiving notification messages,
*
* -
* sending a request message, and
*
* -
* replying to a request message.
*
*
*/
protected enum FeedType
{
/**
* Feed for publishing notification messages.
*/
PUBLISH_FEED,
/**
* Feed for receiving notification messages.
*/
SUBSCRIBE_FEED,
/**
* Feed for placing requests.
*/
REQUEST_FEED,
/**
* Feed for replying to requests.
*/
REPLY_FEED
} // end of enum FeedType
//---------------------------------------------------------------
// Member data.
//
//-----------------------------------------------------------
// Locals.
//
/**
* Specifies whether this is a publish, subscribe, request,
* or reply feed.
*/
protected final FeedType mFeedType;
/**
* The feed interfaces with this eBus subject. The subject
* type is based on {@link #mFeedType feed type}.
*/
protected final ESubject mSubject;
/**
* Tracks the number of contra-feeds matched to this feed. If
* this is a publisher feed, then counts subscriber feeds. If
* a subscriber feed, then counts publisher feeds.
*/
protected int mActivationCount;
/**
* Index in the {@link EFeedList}. Note that a feed is stored
* in only one feed list.
*/
private int mFeedIndex;
//---------------------------------------------------------------
// Member methods.
//
//-----------------------------------------------------------
// Constructors.
//
/**
* Creates a new single eBus feed instance for the given
* parameters.
*
* This constructor is not deprecated since it is
*
* @param client post eBus tasks to this client.
* @param feedScope this feed supports either local, local
* & remote, or just remote feeds.
* @param feedType the actual feed type.
* @param subject interact with this eBus subject.
*/
protected ESingleFeed(final EClient client,
final FeedScope feedScope,
final FeedType feedType,
final ESubject subject)
{
super (client, feedScope);
mFeedType = feedType;
mSubject = subject;
mFeedIndex = -1;
mActivationCount = 0;
} // end of ESingleFeed()
/**
* Creates a new single eBus feed instance based on the
* given builder's settings.
* @param builder contains feed settings.
*/
protected ESingleFeed(final Builder builder)
{
super (builder);
mFeedType = builder.mFeedType;
mSubject = builder.getSubject();
mFeedIndex = -1;
mActivationCount = 0;
} // end of ESingleFeed(Builder)
//
// end of Constructors.
//-----------------------------------------------------------
//-----------------------------------------------------------
// Abstract Method Declarations.
//
/**
* Updates the feed activation count if the feed
* scope supports the contra-feed location. If the activation
* count transitions between activate and inactive, then
* updates the feed.
* @param loc contra-feed location.
* @param fs contra-feed state.
* @return 1 if activated, -1 if deactivated, and zero if
* not affected.
*/
/* package */ abstract int
updateActivation(final EClient.ClientLocation loc,
final EFeedState fs);
//
// end of Abstract Method Declarations.
//-----------------------------------------------------------
//-----------------------------------------------------------
// Object Method Overrides.
//
/**
* Returns a containing the feed message key and data member
* values.
* @return textual representation of this feed.
*/
@Override
public String toString()
{
return (String.format("%s %s %s",
mSubject.key(),
mFeedType,
super.toString()));
} // end of toString()
//
// end of Object Method Overrides.
//-----------------------------------------------------------
//-----------------------------------------------------------
// Get Methods.
//
/**
* Returns the feed message key. The message key type matches
* the feed type. If this is a {@link EPublishFeed}, then a
* {@link net.sf.eBus.messages.ENotificationMessage notification}
* message key is returned.
* @return message key.
*/
@Override
public final EMessageKey key()
{
return (mSubject.key());
} // end of key()
/**
* Returns the feed
* {@link EMessageKey#subject() message key subect}.
* @return message key subject.
*/
public final String messageSubject()
{
return ((mSubject.key()).subject());
} // end of messageSubject()
/**
* Returns the index into the {@link EFeedList}.
* @return feed list index.
*/
/* package */ final int feedIndex()
{
return (mFeedIndex);
} // end of feedIndex()
/**
* Returns the feed activation count.
* @return value ≥ zero.
*/
public final int activationCount()
{
return (mActivationCount);
} // end of activationCount()
//
// end of Get Methods.
//-----------------------------------------------------------
//-----------------------------------------------------------
// Set Methods.
//
/**
* Sets the {@link EFeedList feed list} index to the given
* value.
* @param index the updated feed list index.
*/
/* package */ final void feedIndex(final int index)
{
mFeedIndex = index;
} // end of feedIndex(int)
//
// end of Set Methods.
//-----------------------------------------------------------
//---------------------------------------------------------------
// Inner classes.
//
/**
* Base class for single subject feeds. Contains feed message
* key.
*
* @param feed type.
* @param {@link EObject} sub-type.
* @param builder leaf type.
*/
protected abstract static class Builder>
extends EFeed.Builder
{
//-----------------------------------------------------------
// Member data.
//
//-------------------------------------------------------
// Locals.
//
/**
* Target feed type.
*/
protected final FeedType mFeedType;
/**
* eBus message key. Required for single feeds.
*/
protected EMessageKey mKey;
//-----------------------------------------------------------
// Member methods.
//
//-------------------------------------------------------
// Constructors.
//
/**
* Creates a new single feed builder for the given feed
* type and eBus target feed class.
* @param feedType target feed type.
* @param targetClass target builder class.
*/
protected Builder(final FeedType feedType,
final Class targetClass)
{
super (targetClass);
mFeedType = feedType;
} // end of className(FeedType, Class)
//
// end of Constructors.
//-------------------------------------------------------
//-------------------------------------------------------
// Abstract Method Declarations.
//
/**
* Returns eBus subject for the given message key.
* @return eBus feed subject.
*/
protected abstract ESubject getSubject();
//
// end of Abstract Method Declarations.
//-------------------------------------------------------
//-------------------------------------------------------
// Abstract Method Overrides.
//
/**
* Checks if message key is set.
* @param problems place invalid configuration settings
* in this problems list.
* @return {@code problems} to allow for method chaining.
*/
@Override
protected Validator validate(final Validator problems)
{
return (problems.requireNotNull(mKey, "messageKey"));
} // end of validate(Validator)
//
// end of Abstract Method Overrides.
//-------------------------------------------------------
//-------------------------------------------------------
// Set Methods.
//
/**
* Sets eBus message key defining this feed. Returns
* {@code this Builder} instance so that configuration
* methods may be chained.
* @param key eBus message key.
* @return {@code this Builder} instance.
* @throws NullPointerException
* if {@code target} is {@code null}.
*/
public B messageKey(final EMessageKey key)
{
mKey = Objects.requireNonNull(key, "key is null");
return (self());
} // end of messageKey(EMessageKey)
//
// end of Set Methods.
//-------------------------------------------------------
} // end of class Builder
} // end of class ESingleFeed