Unless it totally broke compatibility of those apps, projects and clients
that we spoke about earlier, I see no problem doing it on master/trunk
either.




On Tue, Oct 18, 2016 at 7:22 PM, Anatole Tresch <atsti...@gmail.com> wrote:

> Currently not. It is not yet pushed, since I have first to reorganize my
> folders with the latest modules changes.
> And first of all I am interested in a content-wise feedback/questions. I
> dont care if we
> put it into branch A or B ... this does not mean I cannot push it into some
> branch.... but this takes more time,
> around WE or so. And I thaught we can start with some basic discussions
> ahead...
>
> 2016-10-18 17:27 GMT+02:00 Werner Keil <werner.k...@gmail.com>:
>
> > Would that be in a separate branch to start with?
> >
> > Werner
> >
> >
> > On Tue, Oct 18, 2016 at 4:42 PM, Anatole Tresch <atsti...@gmail.com>
> > wrote:
> >
> > > Hi all
> > >
> > > based on the work to see how easy some of the ideas of Dimitry (the
> > > designated Oracle spec lead for config) could be implemented I would
> like
> > > to propose some adaptions and changes:
> > >
> > >    - I would basically resolve the current duplication of the builder
> > >    pattern (in the builder module as well as in the core API). The core
> > API
> > >    itself is already based on an interface, which if done right IMO
> gives
> > > all
> > >    the flexibility needed and also would make some of the more implicit
> > >    mechanism more explicit.
> > >    - The main API changes required are on the
> > *ConfigurationContextBuilder*
> > >    SPI interface:
> > >       - this interface as of now already contains methods for adding
> and
> > >       removing of property sources, filters and converters. Most of the
> > > methods
> > >       are implemented in two variants as of now: once taking a
> > Collection,
> > > once
> > >       using an ellipse operator taking single items or arrays.
> > > Unfortunately some
> > >       of the methods are not fully present in both variants, so I
> > > propoase to add
> > >       the missing counterparts. This basically is not a functional
> > change,
> > > but
> > >       makes the API more concise.
> > >       - currently the implementation of the builder implicitly applies
> > >       sorting of property sources and filters using its internal
> sorting
> > >       algorithm. This works well, but in case, where I dont want to use
> > the
> > >       ordinal pattern, e.g. because I have configured a different
> > > hierarchy in a
> > >       XML meta-config file, this implicit sorting makes it hard to
> build
> > > up a
> > >       property source chain in a transparent and clear way (using the
> > > builder). I
> > >       would expect the builder to NOT perform any sorting implicitly.
> > > Instead
> > >       sorting is controlled by calling the appropriate sort methods
> > hereby
> > >       passing a *Comparator*. So I propose to add to methods
> > > *sortPropertySources(Comparator)
> > >       *and *sortPropertyFilters(Comparator) *to the builder interface.
> > >       - Given that the *ConfigurationContextBuilder* actually manages
> an
> > >       ordered list of property sources. In case I want to
> > increase/decrese
> > > the
> > >       priority of a property source or make it the most/least
> significant
> > > one.
> > >       Therefore I propose to add the methods *(incresePriority(
> > > PropertySource),
> > >       decresePriority(PropertySource), lowestPriority(PropertySource),
> > >       highestPriority(PropertySource)*. One use case is creating a
> > builder
> > >       from an existing *ConfigurationContext* and change the priority
> of
> > >       some of its property sources. Also these methods do strictly
> > > operate on the
> > >       ordering only, they will not change implicitly any ordinals.
> > >       - For implementing module it has shown that access tot he current
> > >       property sources, filters and converters of a builder is useful.
> > > Creating a
> > >       context and accessing later does not work, since the builder
> > supports
> > >       building an instance only once. So I propose to add the methods
> > > *getPropertySources(),getPropertyFilters(),
> > >       getPropertyConverter()*.
> > >    - Finally given a *ConfigurationContext* built with the builder, I
> > want
> > >    to create a *Configuration* instance. The corresponding method
> > > *createConfiguration(ConfigurationContext)
> > >    *is already defined on the *ConfigurationProviderSpi* interface. So
> I
> > >    would like to add it as well on the *ConfigurationProvider*.
> Obviously
> > >    building a configuration MUST resepct/ensure the precendece of
> > property
> > >    sources as defined by its context (which by now, was not the case).
> > >
> > > With these changes we have a much better separation of concerns:
> > >
> > >    - we have an ordered list of property sources. The ordering hereby
> can
> > >    be ordinal based (used by default).
> > >    - But using the ConfigurationContextBuilder alternate strategies can
> > be
> > >    easily defined by implementing a different Comparator being used or
> > >    applying the ordering required using the methods offerend on the
> > > builder.
> > >    - Using ordinals is the default way provided, but using modules we
> can
> > >    easily provide alternate strategies as well.
> > >    - This will quite probably also help with contextual aspects, once
> it
> > is
> > >    more clear, what contextuality means regarding configuration and
> also
> > > make
> > >    implementation of a company specific strategy much more easier.
> > >
> > > There is one disadvantage I dont want to omit: the changes in the
> > > implementation are not fully behavioural compatible wuth code that
> > already
> > > is using the builder pattern. Since the method for creating a new
> > > Configuration instance has not been exposed I expect the changes only
> > > affect code within Tamaya itself (basically mostly some testing and
> code
> > in
> > > the core, but not much).
> > >
> > > ​Feedback is welcome. The changes described are actually implemented,
> > > testing and are all working and have proven to work well. So if nobody
> > > complains I will checkin the changes on Thursday-WE the latest.
> > >
> > > J Anatole​
> > >
> > >
> > > ​Following the source of the ConfigurationContextBuilder with marks for
> > > additions:
> > >
> > > /**
> > >  * A builder for creating new or adapting instances of {@link
> > > ConfigurationContext}.
> > >  * Builders can be obtained in exactly two ways:
> > >  * <ol>
> > >  *     <li>By accessing a preinitialized builder from an existing
> > > {@link ConfigurationContext},
> > >  *     by calling {@link
> > > org.apache.tamaya.spi.ConfigurationContext#toBuilder()}.</li>
> > >  *     <li>By accessing an empty builder instance from
> > >  *     {@link org.apache.tamaya.ConfigurationProvider#
> > > getConfigurationContextBuilder()}.</li>
> > >  * </ol>
> > >  * After all changes are applied to a builder a new {@link
> > > ConfigurationContext} instance can
> > >  * be created and can be applied by calling
> > >  * {@link org.apache.tamaya.ConfigurationProvider#
> > > setConfigurationContext(org.apache.tamaya.spi.ConfigurationContext)}.
> > >  *
> > >  */
> > > public interface ConfigurationContextBuilder {
> > >
> > >     /**
> > >      * Init this builder instance with the given {@link
> > > ConfigurationContext} instance. This
> > >      * method will use any existing property sources, filters,
> > > converters and the combination
> > >      * policy of the given {@link ConfigurationContext} and initialize
> > > the current builder
> > >      * with them.
> > >      *
> > >      * @param context the {@link ConfigurationContext} instance to be
> > > used, not null.
> > >      * @return this builder, for chaining, never null.
> > >      */
> > >     ConfigurationContextBuilder setContext(ConfigurationContext
> > context);
> > >
> > >     /**
> > >      * This method can be used for adding {@link PropertySource}s.
> > >      * Hereby the property source is added to the tail of property
> > sources
> > > with
> > >      * lowest priority  regardless of its current ordinal value. To
> > > sort the property
> > >      * sources based on their ordinals call {@kink
> #sortPropertySources}.
> > >      *
> > >      * @param propertySources the PropertySources to add
> > >      * @return this builder, for chaining, never null.
> > >      * @throws IllegalArgumentException If a property source with a
> > > given name already
> > >      * exists.
> > >      */
> > >     ConfigurationContextBuilder addPropertySources(PropertySource...
> > > propertySources);
> > >
> > >     /**
> > >      * This method can be used for programmatically adding {@link
> > > PropertySource}s.
> > >      * Hereby the property source is added to the tail of property
> > sources
> > > with
> > >      * lowest priority regardless of its current ordinal value. To
> > > sort the property
> > >      * sources based on their ordinals call {@kink
> #sortPropertySources}.
> > >      *
> > >      * @param propertySources the PropertySources to add
> > >      * @return this builder, for chaining, never null.
> > >      * @throws IllegalArgumentException If a property source with a
> > > given name already
> > >      * exists.
> > >      */
> > >     ConfigurationContextBuilder
> > > addPropertySources(Collection<PropertySource> propertySources);
> > >
> > >     /**
> > >      * Removes the given property sources, if existing. The existing
> > > order of property
> > >      * sources is preserved.
> > >      *
> > >      * @param propertySources the property sources to remove, not null.
> > >      * @return the builder for chaining.
> > >      */
> > >     ConfigurationContextBuilder
> > > removePropertySources(PropertySource... propertySources);
> > >
> > >     /**
> > >      * Removes the given property sources, if existing. The existing
> > > order of property
> > >      * sources is preserved.
> > >      *
> > >      * @param propertySources the property sources to remove, not null.
> > >      * @return the builder for chaining.
> > >      */
> > >     ConfigurationContextBuilder
> > > removePropertySources(Collection<PropertySource> propertySources);
> > >
> > >     /**
> > >      * Access the current chain of property sources. Items at the end
> > > of the list have
> > >      * precedence/more significance.
> > >      *
> > >      * @return the property source chain, never null.
> > >      */
> > >     List<PropertySource> getPropertySources();
> > >
> > >     /**
> > >      * Access the current chain of property filters. Items at the end
> > > of the list have
> > >      * precedence/more significance.
> > >      *
> > >      * @return the property source chain, never null.
> > >      */
> > >     List<PropertyFilter> getPropertyFilters();
> > >
> > >     /**
> > >      * Access the current registered property converters.
> > >      *
> > >      * @return the current registered property converters.
> > >      */
> > >     Map<TypeLiteral<?>, Collection<PropertyConverter<?>>>
> > > getPropertyConverter();
> > >
> > >     /**
> > >      * Increases the priority of the given property source, by moving
> > > it towards the end
> > >      * of the chain of property sources. If the property source given
> > > is already at the end
> > >      * this method has no effect. This operation does not change any
> > > ordinal values.
> > >      *
> > >      * @param propertySource the property source to be incresed
> > > regarding its significance.
> > >      * @return the builder for chaining.
> > >      * @throws IllegalArgumentException If no such property source
> > > exists in the current
> > >      * chain.
> > >      */
> > >     ConfigurationContextBuilder increasePriority(PropertySource
> > > propertySource);
> > >
> > >     /**
> > >      * Decreases the priority of the given property source, by moving
> > > it towards the start
> > >      * of the chain of property sources. If the property source given
> > > is already the first
> > >      * this method has no effect. This operation does not change any
> > > ordinal values.
> > >      *
> > >      * @param propertySource the property source to be decresed
> > > regarding its significance.
> > >      * @return the builder for chaining.
> > >      * @throws IllegalArgumentException If no such property source
> > > exists in the current
> > >      * chain.
> > >      */
> > >     ConfigurationContextBuilder decreasePriority(PropertySource
> > > propertySource);
> > >
> > >     /**
> > >      * Increases the priority of the given property source to be
> > > maximal, by moving it to
> > >      * the tail of the of property source chain. If the property source
> > > given is
> > >      * already the last item this method has no effect. This operation
> > > does not change
> > >      * any ordinal values.
> > >      *
> > >      * @param propertySource the property source to be maximized
> > > regarding its significance.
> > >      * @return the builder for chaining.
> > >      * @throws IllegalArgumentException If no such property source
> > > exists in the current
> > >      * chain.
> > >      */
> > >     ConfigurationContextBuilder highestPriority(PropertySource
> > > propertySource);
> > >
> > >     /**
> > >      * Decreases the priority of the given property source to be
> > > minimal, by moving it to
> > >      * the start of the chain of property source chain. If the
> > > property source given is
> > >      * already the first item this method has no effect. This
> > > operation does not change
> > >      * any ordinal values.
> > >      *
> > >      * @param propertySource the property source to be minimized
> > > regarding its significance.
> > >      * @return the builder for chaining.
> > >      * @throws IllegalArgumentException If no such property source
> > > exists in the current
> > >      * chain.
> > >      */
> > >     ConfigurationContextBuilder lowestPriority(PropertySource
> > > propertySource);
> > >
> > >     /**
> > >      * Adds the given PropertyFilter instances, hereby the instances
> are
> > > added
> > >      * to the end of the list with highest priority. The ordering of
> > > existing
> > >      * property filters remains unchanged. To sort the property
> > >      * filters call {@kink #sortPropertyFilter}.
> > >      *
> > >      * @param filters the filters to add
> > >      * @return this builder, for chaining, never null.
> > >      */
> > >     ConfigurationContextBuilder addPropertyFilters(PropertyFilter...
> > > filters);
> > >
> > >     /**
> > >      * Adds the given PropertyFilter instances, hereby the instances
> are
> > > added
> > >      * to the end of the list with highest priority. The ordering of
> > > existing
> > >      * property filters remains unchanged. To sort the property
> > >      * filters call {@kink #sortPropertyFilter}.
> > >      *
> > >      * @param filters the filters to add
> > >      * @return this builder, for chaining, never null.
> > >      */
> > >     ConfigurationContextBuilder
> > > addPropertyFilters(Collection<PropertyFilter> filters);
> > >
> > >     /**
> > >      * Removes the given PropertyFilter instances, if existing. The
> > > order of the remaining
> > >      * filters is preserved.
> > >      *
> > >      * @param filters the filter to remove
> > >      * @return this builder, for chaining, never null.
> > >      */
> > >     ConfigurationContextBuilder
> > > removePropertyFilters(PropertyFilter... filters);
> > >
> > >     /**
> > >      * Removes the given PropertyFilter instances, if existing. The
> > > order of the remaining
> > >      * filters is preserved.
> > >      *
> > >      * @param filters the filter to remove
> > >      * @return this builder, for chaining, never null.
> > >      */
> > >     ConfigurationContextBuilder
> > > removePropertyFilters(Collection<PropertyFilter> filters);
> > >
> > >     /**
> > >      * This method can be used for adding {@link PropertyConverter}s.
> > >      * Converters are added at the end after any existing converters.
> > >      * For converters already registered for the current target type
> the
> > >      * method has no effect.
> > >      *
> > >      * @param typeToConvert     the type for which the converter is for
> > >      * @param propertyConverters the PropertyConverters to add for this
> > > type
> > >      * @return this builder, for chaining, never null.
> > >      */
> > >     <T> ConfigurationContextBuilder
> > > addPropertyConverters(TypeLiteral<T> typeToConvert,
> > >
> > > PropertyConverter<T>... propertyConverters);
> > >
> > >     /**
> > >      * This method can be used for adding {@link PropertyConverter}s.
> > >      * Converters are added at the end after any existing converters.
> > >      * For converters already registered for the current target type
> the
> > >      * method has no effect.
> > >      *
> > >      * @param typeToConvert     the type for which the converter is for
> > >      * @param propertyConverters the PropertyConverters to add for this
> > > type
> > >      * @return this builder, for chaining, never null.
> > >      */
> > >     <T> ConfigurationContextBuilder
> > > addPropertyConverters(TypeLiteral<T> typeToConvert,
> > >
> > > Collection<PropertyConverter<T>> propertyConverters);
> > >
> > >     /**
> > >      * Removes the given PropertyConverter instances for the given
> type,
> > >      * if existing.
> > >      *
> > >      * @param typeToConvert the type which the converter is for
> > >      * @param propertyConverters    the converter to remove
> > >      * @return this builder, for chaining, never null.
> > >      */
> > >     <T> ConfigurationContextBuilder
> > > removePropertyConverters(TypeLiteral<T> typeToConvert,
> > >
> > > PropertyConverter<T>... propertyConverters);
> > >
> > >     /**
> > >      * Removes the given PropertyConverter instances for the given
> type,
> > >      * if existing.
> > >      *
> > >      * @param typeToConvert the type which the converter is for
> > >      * @param propertyConverters    the converter to remove
> > >      * @return this builder, for chaining, never null.
> > >      */
> > >     <T> ConfigurationContextBuilder
> > > removePropertyConverters(TypeLiteral<T> typeToConvert,
> > >
> > > Collection<PropertyConverter<T>> propertyConverters);
> > >
> > >     /**
> > >      * Removes all converters for the given type, which actually
> > > renders a given type
> > >      * unsupported for type conversion.
> > >      *
> > >      * @param typeToConvert the type which the converter is for
> > >      * @return this builder, for chaining, never null.
> > >      */
> > >     ConfigurationContextBuilder
> > > removePropertyConverters(TypeLiteral<?> typeToConvert);
> > >
> > >     /**
> > >      * Sorts the current registered property sources using the given
> > > comparator.
> > >      *
> > >      * NOTE: property sources at the beginning have minimal
> significance.
> > >      *
> > >      * @param comparator the comparator to be used, not null.
> > >      * @return this instance for chaining.
> > >      */
> > >     ConfigurationContextBuilder
> > > sortPropertySources(Comparator<PropertySource> comparator);
> > >
> > >     /**
> > >      * Sorts the current registered property filters using the given
> > > comparator.
> > >      *
> > >      * NOTE: property filters at the beginning have minimal
> significance.
> > >      *
> > >      * @param comparator the comparator to be used, not null.
> > >      * @return this instance for chaining.
> > >      */
> > >     ConfigurationContextBuilder
> > > sortPropertyFilter(Comparator<PropertyFilter> comparator);
> > >
> > >     /**
> > >      * Sets the {@link PropertyValueCombinationPolicy} used to
> > > evaluate the final
> > >      * property values.
> > >      *
> > >      * @param policy the {@link PropertyValueCombinationPolicy} used,
> > not
> > > null
> > >      * @return this builder, for chaining, never null.
> > >      */
> > >     ConfigurationContextBuilder
> > > setPropertyValueCombinationPolicy(PropertyValueCombinationPolicy
> > > policy);
> > >
> > >     /**
> > >      * Builds a new {@link ConfigurationContext} based on the data in
> > > this builder. The ordering of property
> > >      * sources and property filters is not changed, regardless of
> > > their ordinals. For ensure a certain
> > >      * ordering/significance call {@link
> > > #sortPropertyFilter(Comparator)} and/or {@link
> > > #sortPropertySources(Comparator)}
> > >      * before building the context.
> > >      *
> > >      * @return the final context to be used to create a configuration.
> > >      * @see org.apache.tamaya.ConfigurationProvider#
> createConfiguration(
> > > ConfigurationContext)
> > >      */
> > >     ConfigurationContext build();
> > >
> > > }​
> > >
> >
>
>
>
> --
> *Anatole Tresch*
> PPMC Member Apache Tamaya
> JCP Star Spec Lead
> *Switzerland, Europe Zurich, GMT+1*
> *maketechsimple.wordpress.com <http://maketechsimple.wordpress.com/> *
> *Twitter:  @atsticks, @tamayaconf*
>

Reply via email to