Naming of Create/Bind/Operator Functions and Types

[benjchristensen]

Changes are being done in #770 as a result of discussion in #746 that add a new bind operator and change the create signature to inject a Subscription instead of returning it. The reasons for this change can be seen at #746.

The names have thus far been left as is or as raw functions while achieving the right functionality. Before releasing and becoming part of the published API I'd like to finalize the names (some of which have been disputed).

1) "source" Function

Action1<Operator<? super T>>

This is the single function that exists inside an Observable that is executed upon subscription (when subscribe is invoked).

The previous function was called OnSubscribeFunc<T>.

We could just keep the Action1 signature but the generics are obnoxious to remember, type and code-complete. Having a specific type is for ease of use.

This will be the most used of the types discussed in this issue as all Observable.create usage will involve this type. Most users of RxJava will use Observable.create.

A possibility is:

public static interface OnSubscribe<T> extends Action1<Operator<? super T>> 

or it could more explicitly (and like OnSubscribeFunc) be:

public static interface OnSubscribe<T> extends Function {
        public void onSubscribe(Operator<? super T> op);        
}

What other names could this be?

2) "bind" or "lift" Method

The new method added to Observable has a name and signature like this:

public <R> Observable<R> bind(final Func1<Operator<? super R>, Operator<? super T>> bind)

The intent is to perform function composition and return a new Observable representing the composition.

Since my computer science, lambda calculus etc is not the greatest, I was calling this bind but after discussion with others it seems this is probably better called lift as per functional programming principles.

That said, there is nothing requiring us to use names such as these.

The intent of this method is to chain together operators for transforming, combining, filtering and operating on data flowing through an Observable and each time it's chained it returns a new Observable.

For example:

Observable<U> ou = Observable<T>.chain(operatorA);
Observable<V> ov = Observable<U>.chain(operatorB);
Observable<W> ow = Observable<V>.chain(operatorC);

Typically this would be used like this:

Observable<W> ow = Observable<T>.chain(operatorA).chain(operatorB).chain(operatorC);

Here are possible names:

public <R> Observable<R> bind(Function<T, R> f)
public <R> Observable<R> lift(Function<T, R> f)
public <R> Observable<R> compose(Function<T, R> f)

What is the correct name for this?

3) "bind" or "lift" Function

The function that the currently named bind takes is:

Func1<Operator<? super R>, Operator<? super T>>

This could be left as is and will generally only be used by people implementing operators. Thus, it is not in the "common path" for using Rx.

However, it could benefit from the clearer communication of a specific type and name.

Possibilities include:

OnBind<R, T>
OnLift<R, T>
BindFunction<R, T>
LiftFunction<R, T>
Composition<R, T>

Should we give this a specific type and name? If so, what should it be?

4) Operator class

As part of the new bind and create functionality that injects Subscriptions into the source function, a new type Operator was created that combines Observer and Subscription.

public abstract class Operator<T> implements Observer<T>, Subscription

Is Operator the correct name? If not, what should it be called?

---

Possible Outcomes

// use `OnSubscribe` for the "source" function
public final static <T> Observable<T> create(final OnSubscribe<T> f);

// use `compose` and `Composition` as user friendly representations for the `bind`/`lift` functionality
public <R> Observable<R> compose(final Composition<R, T> cf);

// leave `Operator` as is
public abstract class Operator<T> implements Observer<T>, Subscription

or

// use `OnSubscribe` for the "source" function
public final static <T> Observable<T> create(final OnSubscribe<T> f);

// use `compose` for the name but leave the function
public <R> Observable<R> compose(final Func1<Operator<? super R>, Operator<? super T>> cf);

// leave `Operator` as is
public abstract class Operator<T> implements Observer<T>, Subscription

or

// use `OnSubscribe` for the "source" function
public final static <T> Observable<T> create(final OnSubscribe<T> f);

// use `lift`
public <R> Observable<R> lift(final Func1<Operator<? super R>, Operator<? super T>> cf);

// leave `Operator` as is
public abstract class Operator<T> implements Observer<T>, Subscription

etc

---

My intent is to solidify the naming before releasing 0.17.0 as these are not easy to change once released.

Please provide your suggestions and reasoning either to support one of the options above or for something new.

Thank you!

[akarnokd]

How about

Observable<T> o = Observable.<T>with(operatorA).with(operatorB).with(operatorC);

[headinthebox]

public Observable bind(final Func1<Operator<? super R>, Operator<? super T>> bind)

This is actually an instance of map since it takes (Operator->Operator) to (Observable->Observable), so "lift" would be the geek name. I like @akarnokd proposal to use leverage English to emphasize the fluent style. Using "with" sounds OK.

[headinthebox]

Func1<Operator<? super R>, Operator<? super T>>

For this one, I actually like keeping Func1; otherwise I'd have to unfold the synonym. That is because I remember

(Operator<S>->Operator<T>) ->(Observable<T>->Observable<T>)

That is easier than

(XXX<S,T>) -> (Observable->Observable)

[headinthebox]

public static interface OnSubscribe extends Action1<Operator<? super T>>

I like this one. With

public static interface OnSubscribe<T> extends Function {
        public void onSubscribe(Operator<? super T> op);        
}

I need to mentally translate too much.

[headinthebox]

public abstract class Operator implements Observer, Subscription

Can't we just make Observer implement Subscription? Less types is better.

[headinthebox]

This would be my choice. As I said not sure the last one works.

// use `OnSubscribe` for the "source" function
public final static <T> Observable<T> create(final OnSubscribe<T> f);

// use `with` for the name but leave the function
public <R> Observable<R> with(final Func1<Observer<? super R>, Observer<? super T>> cf);

// Modify Observer
public abstract class Observer<T> implements  Subscription { .... }

[samuelgruetter]

Note that with is a keyword in Scala, so in Scala we'll need a different name.

[headinthebox]

What would be a good word for "before". Since "bind" is contravariant, it chains the transformations in reverse order. In my younger days when Algol 68 was all the rage if then else fi, while do od, case esac, I would propose neht, but I am sure that this would not fly in 2014 ;-)

[duarten]

I'm not sure if I like having Observer implementing a Subscription. Now you can have the same Observer instance subscribed to more than one Observable if you so wish, and what you unsubscribe is the Observable <-> Observer association. I guess it would be okay if Observer were to become only an internal type. Also, there might be some strangeness with Subjects.

[abersnaze]

After playing with this last night I'm beginning to like the idea of changing Observable to a abstract class that extends CompositeSubscription. The two argument creators on Operator seem awkward. Does it make sense to allow the same Subscription was used to create two different Operators with different Observables or vice versa? If Observable was the Operator you wouldn't need any of that.

Changing from an interface to an abstract class would minimize the breakiness to just forcing everyone to switch from implements to extends for just named classes (anonymous inner classes wouldn't need to change).

Come to think of it are there any other Subscription types? Should we think of this as renaming CompositeSubscription to Observer and adding three abstract methods onNext,onError,onCompleted?

[benjchristensen]

I too don't think making Observer extend Subscription is a good approach.

1) Conflates Responsibility

When using an Observable it is rare that someone needs to concern themselves with the Subscription unless they are implementing an operator. By making Observer extend Subscription we would be forcing all users to always concern themselves with it.

What does implementing unsubscribe even mean when just providing an Observer to an Observable.subscribe(Observer) when one just wants to subscribe to the data?

This is what we (users) would have to implement:

    new Observer<String>() {

        @Override
        public void onCompleted() {

        }

        @Override
        public void onError(Throwable e) {

        }

        @Override
        public void onNext(String args) {

        }

        public final void unsubscribe() {
            // what to do here?
        }

    }

In most cases I don't know what the unsubscribe method should do. It certainly wouldn't be implemented correctly.

Contrast this with the current Observable.subscribe which handles the subscription:

public final Subscription subscribe(Observer<? super T> observer)  {
   ... simplified ...
   Operator<T> op = Operator.create(observer, new CompositeSubscription());
   subscribe(op);
   return op;
}

This is not logic that most users of Rx should ever have to worry about.

I feel that Observer and Subscription should be kept separate and that we have a type such as the current Operator that combines them when needed.

2) Major Breaking Change

This would be a massive breaking change to anyone using RxJava. There is no mechanism for making it backwards compatible or providing a deprecation strategy.

[abersnaze]

I'm not sure if you were replying directly to my statement. What about making Observer and abstract class where unsubscribe() in implemented for you? In fact it should probably be final so that users would have to add(Subscription) to register a unsubscribe callback when needed.

[benjchristensen]

I'm not sure if you were replying directly to my statement.

I was replying to @headinthebox but it applies to yours as well (we posted within minutes of each other).

What about making Observer and abstract class where unsubscribe() in implemented for you?

Perhaps, but it's still a pretty major breaking change.

I can see some limited benefit in an Observer being able to call unsubscribe, but that is supported by the subscribe(Operator) interface and it's very rare that people are doing that in the final Observer since they generally should be using things like take and takeUntil for controlling when an Observable is unsubscribed.

The problem obviously is that we now have 2 ways of subscribing:

public Subscription subscribe(Observer<? super T> observer)

and

public void subscribe(Operator<? super T> o)

So the real question is whether we are willing to have a massive breaking change where we eliminate all of the subscribe methods that return Subscription. And if so, why are they called subscribe anymore? Perhaps just observe?

If we were starting from scratch I wouldn't have the Subscription subscribe(Observer) methods, only void observe(Observer)