Using FluxC

There are a few working examples of using FluxC as a library. See the FluxC Example app and Instaflux.

The following examples use snippets from the FluxC Example app.

Initial setup

See the example app for guidance on how to set up FluxC in a new app.

Using a Store in an Activity or Fragment

• Add the activity to the Component
• Inject the fragment into the current Component instance when the activity is created onCreate:

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    ((ExampleApp) getApplication()).component().inject(this);
    ...

• Inject any needed FluxC stores:

public class PostsFragment extends Fragment {
    @Inject PostStore mPostStore;
    ...

The injected PostStore can now be used to fetch data from the store.

mPostStore.getPostsForSite(mSite);

Only read actions are available in this way - anything that involves making a network request or altering the local storage requires use of Actions and the Dispatcher.

Using the Dispatcher

The same prerequisites as above apply for the Dispatcher - the activity using it must be registered with the Component, and the activity should be injected.

Next, inject the Dispatcher into the activity:

public class PostsFragment extends Fragment {
    @Inject PostStore mPostStore;
    @Inject Dispatcher mDispatcher;
    ...

An additional requirement for using the Dispatcher is that the actvity needs to register and unregister itself with the dispatcher as part of its life cycle. For example:

@Override
public void onStart() {
    super.onStart();
    mDispatcher.register(this);
}

@Override
public void onStop() {
    super.onStop();
    mDispatcher.unregister(this);
}

We can now dispatch actions. For example, let's fetch a list of posts from a user's site. This will involve the PostStore, and the FETCH_POSTS action (all actions supported by each store can be found here).

To dispatch an action, we must first create an Action object. All available actions for a store will be accessible as methods of that store's ActionBuilder. For example, to make a FETCH_POSTS request, we build a FETCH_POSTS action:

PostActionBuilder.newFetchPostAction();

Each method requires a specific Payload type (some may require no Payload at all). In this case, we need to pass newFetchPostAction() a FetchPostsPayload.

FetchPostsPayload payload = new FetchPostsPayload(mSite);
mDispatcher.dispatch(PostActionBuilder.newFetchPostsAction(payload));

Dispatched actions will eventually result (asynchronously) in an OnChanged event, which the dispatching activity or fragment should listen for if it needs to act on the results of the action.

Note: For the dispatcher to work, the activity or fragment using it must be subscribed to at least one OnChanged event.

Receiving OnChanged events

Any dispatched action will eventually result in a OnChanged event. This event will be emitted asynchronously, and the calling activity needs to listen for the event in order to be notified of the result of the action.

For example, a FETCH_POSTS action will result in a OnPostChanged event once the network call has completed and the database updated:

@SuppressWarnings("unused")
@Subscribe(threadMode = ThreadMode.MAIN)
public void onPostChanged(OnPostChanged event) {
	if (event.isError()) {
		prependToLog("Error from " + event.causeOfChange + " - error: " + event.error.type);
		return;
	}

	if (event.causeOfChange.equals(PostAction.FETCH_POSTS)) {
		prependToLog("Fetched " + event.rowsAffected + " posts from: " + firstSite.getName());
	}
}

Notes:

• All actions generate an OnChanged event, whether they succeeded or not
• The same OnChanged event is emitted in case of success or failure; the difference is that OnChanged.isError() will be true in case of failure, and OnChanged.error will contain error details
• Some OnChanged events have a causeOfChange field, which specifies the action that resulted in this OnChanged event. For example, the FETCH_POSTS and DELETE_POST actions both result in an OnPostChanged action, and we can check the origin using causeOfChange. OnPostUploaded, on the other hand, is only emitted as a result of PUSH_POST, and so doesn't have a causeOfChange.

Working with Models

Creating models

The way to create a new model depends on what you intend to do with it.

'Draftable' models

'Draftable' models, like posts and media, which we store local-only versions of, should not be created directly using new XModel(). This is because the model won't exist in the local DB and so lack a local ID, and this may cause unexpected behaviour when attempting to save the model later on.

To receive a new model with a local ID, use instantiate methods from the corresponding Store. For example,

mPostStore.instantiatePostModel();

Non-'draftable' models

Non-'draftable' models, that aren't intended to be persisted before they're uploaded, should be instantiated as normal objects (new XModel()).

Using models

For consistency and clarity, avoid passing pieces of models (e.g. the ID) between activities or fragments, and instead serialize and de-serialize the entire model.