From d814b12bd39172bc59fcefa5815bc3776b793177 Mon Sep 17 00:00:00 2001 From: Tavian Barnes Date: Wed, 7 May 2014 21:58:15 -0400 Subject: listbinder: Add an implementation of ListBinder. --- .../tavianator/sangria/listbinder/ListBinder.java | 427 +++++++++++++++++++++ 1 file changed, 427 insertions(+) create mode 100644 sangria-listbinder/src/main/java/com/tavianator/sangria/listbinder/ListBinder.java (limited to 'sangria-listbinder/src/main/java/com/tavianator/sangria/listbinder/ListBinder.java') diff --git a/sangria-listbinder/src/main/java/com/tavianator/sangria/listbinder/ListBinder.java b/sangria-listbinder/src/main/java/com/tavianator/sangria/listbinder/ListBinder.java new file mode 100644 index 0000000..c28d758 --- /dev/null +++ b/sangria-listbinder/src/main/java/com/tavianator/sangria/listbinder/ListBinder.java @@ -0,0 +1,427 @@ +/**************************************************************************** + * Sangria * + * Copyright (C) 2014 Tavian Barnes * + * * + * 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 com.tavianator.sangria.listbinder; + +import java.lang.annotation.Annotation; +import java.util.*; +import javax.inject.Inject; +import javax.inject.Provider; + +import com.google.common.base.Function; +import com.google.common.base.Objects; +import com.google.common.collect.ArrayListMultimap; +import com.google.common.collect.FluentIterable; +import com.google.common.collect.ListMultimap; +import com.google.inject.AbstractModule; +import com.google.inject.Binder; +import com.google.inject.CreationException; +import com.google.inject.Injector; +import com.google.inject.Key; +import com.google.inject.TypeLiteral; +import com.google.inject.binder.LinkedBindingBuilder; +import com.google.inject.multibindings.Multibinder; +import com.google.inject.spi.Message; +import com.google.inject.util.Types; + +import com.tavianator.sangria.core.PotentialAnnotation; +import com.tavianator.sangria.core.PrettyTypes; +import com.tavianator.sangria.core.Priority; +import com.tavianator.sangria.core.TypeLiterals; +import com.tavianator.sangria.core.UniqueAnnotations; + +/** + * A multi-binder with guaranteed order. + * + *

+ * {@link ListBinder} is much like {@link Multibinder}, except it provides a guaranteed iteration order, and binds a + * {@link List} instead of a {@link Set}. For example: + *

+ * + * 
+ * ListBinder listBinder = ListBinder.build(binder(), String.class)
+ *         .withDefaultPriority();
+ * listBinder.addBinding().toInstance("a");
+ * listBinder.addBinding().toInstance("b");
+ *
+ * + *

+ * This will create a binding for a {@code List}, which contains {@code "a"} followed by {@code "b"}. It also + * creates a binding for {@code List>} — this may be useful in more advanced cases to allow list + * elements to be lazily loaded. + *

+ * + *

To add an annotation to the list binding, simply write this:

+ * + * 
+ * ListBinder listBinder = ListBinder.build(binder(), String.class)
+ *         .annotatedWith(Names.named("name"))
+ *         .withDefaultPriority();
+ *
+ * + *

+ * and the created binding will be {@code @Named("name") List} instead. + *

+ * + *

+ * For large lists, it may be helpful to split up their specification across different modules. This is accomplished by + * specifying priorities for the {@link ListBinder}s when they are created. For example: + *

+ * + * 
+ * // In some module
+ * ListBinder listBinder1 = ListBinder.build(binder(), String.class)
+ *         .withPriority(0);
+ * listBinder1.addBinding().toInstance("a");
+ * listBinder1.addBinding().toInstance("b");
+ *
+ * // ... some other module
+ * ListBinder listBinder2 = ListBinder.build(binder(), String.class)
+ *         .withPriority(1);
+ * listBinder2.addBinding().toInstance("c");
+ * listBinder2.addBinding().toInstance("d");
+ *
+ * + *

+ * The generated list will contain {@code "a"}, {@code "b"}, {@code "c"}, {@code "d"}, in order. This happens because + * the first {@link ListBinder} had a smaller priority, so its entries come first. For more information about the + * priority system, see {@link Priority}. + *

+ * + * @param The type of the list element. + * @author Tavian Barnes (tavianator@tavianator.com) + * @version 1.1 + * @since 1.1 + */ +public class ListBinder { + private static final Class[] SKIPPED_SOURCES = { + ListBinder.class, + BuilderImpl.class, + }; + + private final Binder binder; + private final Multibinder> multibinder; + private final Multibinder> errorMultibinder; + private final TypeLiteral entryType; + private final Key> listKey; + private final Key>> listOfProvidersKey; + private final Key>> setKey; + private final Key>> errorSetKey; + private final PotentialAnnotation potentialAnnotation; + private final Priority initialPriority; + private Priority priority; + + private ListBinder( + Binder binder, + TypeLiteral entryType, + PotentialAnnotation potentialAnnotation, + Priority initialPriority) { + this.binder = binder; + this.entryType = entryType; + + TypeLiteral> elementType = listElementOf(entryType); + TypeLiteral> errorsType = listBinderErrorsOf(entryType); + this.listKey = potentialAnnotation.getKey(TypeLiterals.listOf(entryType)); + this.listOfProvidersKey = potentialAnnotation.getKey(TypeLiterals.listOf(TypeLiterals.providerOf(entryType))); + this.setKey = potentialAnnotation.getKey(TypeLiterals.setOf(elementType)); + this.errorSetKey = potentialAnnotation.getKey(TypeLiterals.setOf(errorsType)); + this.multibinder = potentialAnnotation.accept(new MultibinderMaker<>(binder, elementType)); + this.errorMultibinder = potentialAnnotation.accept(new MultibinderMaker<>(binder, errorsType)); + + this.potentialAnnotation = potentialAnnotation; + this.priority = this.initialPriority = initialPriority; + } + + @SuppressWarnings("unchecked") + private static TypeLiteral> listElementOf(TypeLiteral type) { + return (TypeLiteral>)TypeLiteral.get(Types.newParameterizedType(ListElement.class, type.getType())); + } + + @SuppressWarnings("unchecked") + private static TypeLiteral> listBinderErrorsOf(TypeLiteral type) { + return (TypeLiteral>)TypeLiteral.get(Types.newParameterizedType(ListBinderErrors.class, type.getType())); + } + + /** + * {@link PotentialAnnotation.Visitor} that makes {@link Multibinder}s with the given annotation. + */ + private static class MultibinderMaker implements PotentialAnnotation.Visitor> { + private final Binder binder; + private final TypeLiteral type; + + MultibinderMaker(Binder binder, TypeLiteral type) { + this.binder = binder; + this.type = type; + } + + @Override + public Multibinder visitNoAnnotation() { + return Multibinder.newSetBinder(binder, type); + } + + @Override + public Multibinder visitAnnotationType(Class annotationType) { + return Multibinder.newSetBinder(binder, type, annotationType); + } + + @Override + public Multibinder visitAnnotationInstance(Annotation annotation) { + return Multibinder.newSetBinder(binder, type, annotation); + } + } + + /** + * Start building a {@link ListBinder}. + * + * @param binder The current binder, usually {@link AbstractModule#binder()}. + * @param type The type of the list element. + * @param The type of the list element. + * @return A fluent builder. + */ + public static AnnotatedListBinderBuilder build(Binder binder, Class type) { + return build(binder, TypeLiteral.get(type)); + } + + /** + * Start building a {@link ListBinder}. + * + * @param binder The current binder, usually {@link AbstractModule#binder()}. + * @param type The type of the list element. + * @param The type of the list element. + * @return A fluent builder. + */ + public static AnnotatedListBinderBuilder build(Binder binder, TypeLiteral type) { + return new BuilderImpl<>(binder.skipSources(SKIPPED_SOURCES), type, PotentialAnnotation.none()); + } + + private static class BuilderImpl implements AnnotatedListBinderBuilder { + private final Binder binder; + private final TypeLiteral entryType; + private final PotentialAnnotation potentialAnnotation; + + BuilderImpl(Binder binder, TypeLiteral type, PotentialAnnotation potentialAnnotation) { + this.binder = binder; + this.entryType = type; + this.potentialAnnotation = potentialAnnotation; + } + + @Override + public ListBinderBuilder annotatedWith(Class annotationType) { + return new BuilderImpl<>(binder, entryType, potentialAnnotation.annotatedWith(annotationType)); + } + + @Override + public ListBinderBuilder annotatedWith(Annotation annotation) { + return new BuilderImpl<>(binder, entryType, potentialAnnotation.annotatedWith(annotation)); + } + + @Override + public ListBinder withDefaultPriority() { + return create(Priority.getDefault()); + } + + @Override + public ListBinder withPriority(int weight, int... weights) { + return create(Priority.create(weight, weights)); + } + + private ListBinder create(Priority priority) { + ListBinder listBinder = new ListBinder<>(binder, entryType, potentialAnnotation, priority); + + // Add the delayed errors + Message duplicateBindersError = new Message(PrettyTypes.format("Duplicate %s", listBinder)); + Message conflictingDefaultExplicitError; + if (priority.isDefault()) { + conflictingDefaultExplicitError = new Message(PrettyTypes.format("%s conflicts with ListBinder with explicit priority", listBinder)); + } else { + conflictingDefaultExplicitError = new Message(PrettyTypes.format("%s conflicts with ListBinder with default priority", listBinder)); + } + listBinder.errorMultibinder.addBinding().toInstance(new ListBinderErrors( + priority, + duplicateBindersError, + conflictingDefaultExplicitError)); + + // Set up the exposed bindings + binder.bind(listBinder.listOfProvidersKey) + .toProvider(new ListOfProvidersProvider<>(listBinder)); + binder.bind(listBinder.listKey) + .toProvider(new ListOfProvidersAdapter<>(listBinder.listOfProvidersKey)); + + return listBinder; + } + } + + /** + * Provider implementation for {@code List>}. + */ + private static class ListOfProvidersProvider implements Provider>> { + private final Key>> setKey; + private final Key>> errorSetKey; + private final Priority priority; + private List> providers; + + ListOfProvidersProvider(ListBinder listBinder) { + this.setKey = listBinder.setKey; + this.errorSetKey = listBinder.errorSetKey; + this.priority = listBinder.initialPriority; + } + + @Inject + void inject(Injector injector) { + validate(injector); + initialize(injector); + } + + private void validate(Injector injector) { + // Note that here we don't report all errors at once, correctness relies on Guice injecting even providers + // that get de-duplicated. This way, all errors are attached to the right source. + + List messages = new ArrayList<>(); + + // Get the errors into a multimap by priority + Set> errorSet = injector.getInstance(errorSetKey); + ListMultimap> errorMap = ArrayListMultimap.create(); + for (ListBinderErrors errors : errorSet) { + errorMap.put(errors.priority, errors); + } + + // Check for duplicate priorities + List> ourPriorityErrors = errorMap.get(priority); + ListBinderErrors ourErrors = ourPriorityErrors.get(0); + if (ourPriorityErrors.size() > 1) { + messages.add(ourErrors.duplicateBindersError); + } + + // Check for default and non-default priorities + if (errorMap.containsKey(Priority.getDefault()) && errorMap.keySet().size() > 1) { + messages.add(ourErrors.conflictingDefaultExplicitError); + } + + if (!messages.isEmpty()) { + throw new CreationException(messages); + } + } + + private void initialize(final Injector injector) { + Set> set = injector.getInstance(setKey); + List> elements = new ArrayList<>(set); + Collections.sort(elements); + + this.providers = FluentIterable.from(elements) + .transform(new Function, Provider>() { + @Override + public Provider apply(ListElement input) { + return injector.getProvider(input.key); + } + }) + .toList(); + } + + @Override + public List> get() { + return providers; + } + + @Override + public boolean equals(Object obj) { + if (obj == this) { + return true; + } else if (!(obj instanceof ListOfProvidersProvider)) { + return false; + } + + ListOfProvidersProvider other = (ListOfProvidersProvider)obj; + return setKey.equals(other.setKey); + } + + @Override + public int hashCode() { + return setKey.hashCode(); + } + } + + /** + * Provider implementation for {@code List}, in terms of {@code List>}. + */ + private static class ListOfProvidersAdapter implements Provider> { + private final Key>> providerListKey; + private Provider>> provider; + + ListOfProvidersAdapter(Key>> providerListKey) { + this.providerListKey = providerListKey; + } + + @Inject + void inject(final Injector injector) { + this.provider = injector.getProvider(providerListKey); + } + + @Override + public List get() { + return FluentIterable.from(provider.get()) + .transform(new Function, T>() { + @Override + public T apply(Provider input) { + return input.get(); + } + }) + .toList(); + } + + @Override + public boolean equals(Object obj) { + if (obj == this) { + return true; + } else if (!(obj instanceof ListOfProvidersAdapter)) { + return false; + } + + ListOfProvidersAdapter other = (ListOfProvidersAdapter)obj; + return providerListKey.equals(other.providerListKey); + } + + @Override + public int hashCode() { + return Objects.hashCode(providerListKey); + } + } + + /** + * Add an entry to the list. + * + *

+ * The entry will be added in order for this {@link ListBinder} instance. Between different {@link ListBinder}s, the + * order is determined by the {@link ListBinder}'s {@link Priority}. + *

+ * + * @return A fluent binding builder. + */ + public LinkedBindingBuilder addBinding() { + Key key = Key.get(entryType, UniqueAnnotations.create()); + multibinder.addBinding().toInstance(new ListElement<>(key, priority)); + priority = priority.next(); + return binder.bind(key); + } + + @Override + public String toString() { + return PrettyTypes.format("ListBinder<%s>%s with %s", + entryType, + (potentialAnnotation.hasAnnotation() ? " annotated with " + potentialAnnotation : ""), + initialPriority); + } +} -- cgit v1.2.3