Package name for cdi based apis

[Emily Jiang]

I would like to propose to a naming convention for cdi-based apis.

In most specs, we have cdi-based apis. So far we have two different flavour e.g.

in Fault Tolerance
org.eclipse.microprofile.fault.tolerance.cdi

in Config
org.eclipse.microprofile.config.inject

I feel it is better to use xx.cdi instead of xx.inject, as not all APIs are to be used with @Inject. Once we reach the general consensus, we will use this naming convention for all other specs if applicable. Thoughts?

Emily

[Ken Finnigan]

What's the reasoning for a separate package for CDI APIs?

Can't it just be: org.eclipse.microprofile.fault.tolerance?

Ken

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.
To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/46d90c85-d3b6-4d1d-aa6a-ad51a7b1d4dd%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Emily Jiang]

We can be very clear that it is cdi based. In this way, it is consistent with other specs, e.g. config, health etc.

Emily

On Friday, May 19, 2017 at 7:16:15 PM UTC+1, Ken Finnigan wrote:

What's the reasoning for a separate package for CDI APIs?

Can't it just be: org.eclipse.microprofile.fault.tolerance?

Ken

On Thu, May 18, 2017 at 5:45 PM, 'Emily Jiang' via MicroProfile <microp...@googlegroups.com> wrote:

I would like to propose to a naming convention for cdi-based apis.

In most specs, we have cdi-based apis. So far we have two different flavour e.g.

in Fault Tolerance
org.eclipse.microprofile.fault.tolerance.cdi

in Config
org.eclipse.microprofile.config.inject

I feel it is better to use xx.cdi instead of xx.inject, as not all APIs are to be used with @Inject. Once we reach the general consensus, we will use this naming convention for all other specs if applicable. Thoughts?

Emily

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.

[Ken Finnigan]

Does it need to be explicit in that way?

Seems to be something that we've fallen into rather than an explicit decision made about it, though I could be forgetting.

I'm more concerned with an appropriate pattern than conforming to what's been done before, if there was no explicit decision.

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/cd28418d-523e-4ba4-8bf8-815e449799c3%40googlegroups.com.

[Alasdair Nottingham]

I know Ken isn’t keen on the separation, but I prefer inject or context to cdi because it fits better with the Java EE spec packages precedent. javax.inject, javax.enterprise.inject and javax.enterprise.context, javax.batch.runtime.context and javax.faces.context

Alasdair

[Ken Finnigan]

I'd be ok with the inject and context package names, where appropriate, thus separating the different parts of CDI APIs into their respective parts.

I just wasn't in favor of an arbitrary "cdi" separation

Ken

On Fri, May 19, 2017 at 10:30 PM, Alasdair Nottingham <alasdair....@gmail.com> wrote:

I know Ken isn’t keen on the separation, but I prefer inject or context to cdi because it fits better with the Java EE spec packages precedent. javax.inject, javax.enterprise.inject and javax.enterprise.context, javax.batch.runtime.context and javax.faces.context

Alasdair

On May 18, 2017, at 5:45 PM, 'Emily Jiang' via MicroProfile <microp...@googlegroups.com> wrote:

I would like to propose to a naming convention for cdi-based apis.

In most specs, we have cdi-based apis. So far we have two different flavour e.g.

in Fault Tolerance
org.eclipse.microprofile.fault.tolerance.cdi

in Config
org.eclipse.microprofile.config.inject

I feel it is better to use xx.cdi instead of xx.inject, as not all APIs are to be used with @Inject. Once we reach the general consensus, we will use this naming convention for all other specs if applicable. Thoughts?

Emily

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/46d90c85-d3b6-4d1d-aa6a-ad51a7b1d4dd%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/FCDFEB34-6141-4297-AD4B-5D69415C14BC%40gmail.com.

[Ondrej Mihályi]

I'd be ok with the inject and context package names

 

This makes sense to me. In fact, the Config spec also uses "inject" instead of "cdi" to follow the naming used in javax.inject: https://github.com/eclipse/microprofile-config/tree/master/api/src/main/java/org/eclipse/microprofile/config/inject

--Ondrej

On Sunday, May 21, 2017 at 3:28:06 AM UTC+2, Ken Finnigan wrote:

I'd be ok with the inject and context package names, where appropriate, thus separating the different parts of CDI APIs into their respective parts.

I just wasn't in favor of an arbitrary "cdi" separation

Ken

On Fri, May 19, 2017 at 10:30 PM, Alasdair Nottingham <alasdair....@gmail.com> wrote:

I know Ken isn’t keen on the separation, but I prefer inject or context to cdi because it fits better with the Java EE spec packages precedent. javax.inject, javax.enterprise.inject and javax.enterprise.context, javax.batch.runtime.context and javax.faces.context

Alasdair

On May 18, 2017, at 5:45 PM, 'Emily Jiang' via MicroProfile <microp...@googlegroups.com> wrote:

I would like to propose to a naming convention for cdi-based apis.

In most specs, we have cdi-based apis. So far we have two different flavour e.g.

in Fault Tolerance
org.eclipse.microprofile.fault.tolerance.cdi

in Config
org.eclipse.microprofile.config.inject

I feel it is better to use xx.cdi instead of xx.inject, as not all APIs are to be used with @Inject. Once we reach the general consensus, we will use this naming convention for all other specs if applicable. Thoughts?

Emily

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/46d90c85-d3b6-4d1d-aa6a-ad51a7b1d4dd%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

[Ondrej Mihályi]

I started to document this in the wiki: https://wiki.eclipse.org/MicroProfile/ContributingGuidelines#CDI_API_package_names.

I only mentioned using "inject" to keep things simple. Feel free to update the wiki, e.g. if you also want to use "context" in package names.

I also created a specification checklist that includes all the things we shouldn't forget before we release a spec (legal stuff, common naming cnventions, etc.): https://wiki.eclipse.org/MicroProfile/SpecChecklist

--Ondrej

[John D. Ament]

As an end user, the separation is confusing.  I don't see why I need a different package for what are effectively the annotations used within my project.  In almost all cases, these are core for how they are used and represent the programming model I would to see when using a CDI based Microprofile runtime.

John

[Antoine Sabot-Durand]

I agree with John: what’s the point to add this information. It can only bring confusion.

Antoine

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/5eb3fe03-76bc-4c33-bb2d-287a4822fff4%40googlegroups.com.

[Emily Jiang]

It is nice to make extra clear about the CDIness. In this way, all specs can follow the same pattern. There is nothing wrong to say org.eclipse.microprofile.health.inject. I think it is clearer that it is cdi based just to say org.eclipse.microprofile.health. Remember not all sepcs are cdi required. We need to plan for that.

Emily

[Alasdair Nottingham]

It is also consistent with the precedent set by Java EE which I think is a good thing.

Alasdair

[Ondrej Mihályi]

I'm really undecided on this.

What Emily said makes sense when a spec supports plain Java SE without CDI. This worked well while delivering the config spec and helped to make clear what wouldn't be supported without CDI.

On the other hand, we want to follow the CDI-first approach with the other specs. In that case it is unnatural to put everything in the "inject" subpackage or, on the other hand, confusing to separate the API into normal and CDI packages if we only target CDI initially. Then it makes sense to me to put everything in the base package to make things less confusing. It would make it harder to separate a non-CDI subset later, but that's probably not our goal with most MicroProfile specs. If another spec has a requirement to provide also separate non-CDI, it could package the non-CDI subset in a "base" or "core" subpackage from the beginning.

2 worlds meet here:

 - consistency with Java EE

 - pragmatic and user-centered approach, deferring consistency with Java EE until any JSR is submitted

After studying some Java EE APIs, I'm now inclined more towards the second, because even Java EE isn't consistent on this. E.g. JAX-RS API (already in MicroProfile) includes all annotations in the main package (although none is bound to CDI, rather to JAX-RS own DI). JSF includes the ViewScoped annotation in a general subpackage javax.faces.view, with other non-CDI classes. I couldn't find an example in any Java EE API where CDI parts would be clearly separated. The javax.inject and javax.enterprise.inject packages are separated only because they are defined by the CDI and JSR 330 themselves, which use them as their top packages.

So my final stand is to put the CDI parts of the API into the main package. In case of config and possibly other specs where we want to have a clear separation of plain non-CDI API, we could separate the non-CDI classes into a core/base subpackage.

--Ondrej

[Emily Jiang]

Actually, I vote to use .inject package for the following reasons:

1. It is very clear that the APIS needs CDI.
Even though we do CDI-first, most of the time, we need to add non-CDI classes etc. For some specs, e.g. security or messaging maybe, they might be irrelevant to CDI. Their package will not have .inject. In this case, we are very clear that the specs don't rely on CDI.

2. all specs can then follow the same package name convention.

Ondrej, you pointed out JavaEE are not consistent and ignore the fact some apis depend on CDI. Personally, I wished JavaEE differentiate the apis to ease integration.  I think we should do a better job by clearly identifying which ones are CDI-based to make developers and implementators life easier.

Emily

[Ken Finnigan]

This gets back to my original objection to "cdi" as a package name.

And that is, why do the API classes/annotations/whatever need to be in separate package namespaces?

Why can't everything for fault tolerance be in org.eclipse.microprofile.faulttolerance?

Ken

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/8404cb26-c165-4817-9219-dc83e5d2a24e%40googlegroups.com.

[Emily Jiang]

Ken,

We have two options:
1. ignore the fact of CDIness, leave everything in org.eclipse.microprofile.

faulttolerance
2. explicitly announcing CDIness, keep the CDI-based apis under org.eclipse.microprofile.

faulttolerance.inject


With option 2, it gives us more advantages:
1. clearly announce the cdi dependencies
2. for all non-cdi apis, it can end up in org.eclipse.microprofile.

faulttolerance
3. with this naming convention, for other specs without needing cdi, they can directly put their apis under a package e.g. org.eclipse.microprofiel.jwt, which tells us there is no cdi dependencies.

I think with the extra .inject, it gives us more advantages without any disadvantages. If I still cannot persuade you, we can start a vote.

Emily

[Ondrej Mihályi]

Hi Emily,

I think that the advantages you pointed out can be simply aggregated into a single one: It makes it easy to separate the non-CDI API subset and use it if CDI isn't present.

On the other hand, there's a single disadvantage: Complexity, because having 2 packages instead of one may be confusing to users who want to use the CDI-based API.

I'd run a poll about this. It's more a matter of taste and what we want to focus on. I'd personally prefer simplicity and put everything in a single package, because I think that focus in users and easy adoption is more important than focus on spec creators (us) or spec implementors (vendors).

--Ondrej

[Ken Finnigan]

Emily,

Personally I don't see the need to separate CDI specific API classes into a separate package.

At the end of it all, it's just part of an API for Fault Tolerance, or anything else.

If we were talking about an API with a hundred or so classes, then it makes sense to split it out into sub packages, but as Ondrej mentioned I think its simpler to keep it in a single package.

Ken

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/f1213b66-6b6e-411a-b650-7ed28084be45%40googlegroups.com.

[Emily Jiang]

ok, Ken. Points taken. Do we want to set up a naming convention for every project or it does not matter? Maybe each spec can decide themselves.

Emily

On Sunday, May 28, 2017 at 2:40:07 AM UTC+1, Ken Finnigan wrote:

Emily,

Personally I don't see the need to separate CDI specific API classes into a separate package.

At the end of it all, it's just part of an API for Fault Tolerance, or anything else.

If we were talking about an API with a hundred or so classes, then it makes sense to split it out into sub packages, but as Ondrej mentioned I think its simpler to keep it in a single package.

Ken

On Sat, May 27, 2017 at 4:50 PM, Ondrej Mihályi <ondrej....@gmail.com> wrote:

Hi Emily,

I think that the advantages you pointed out can be simply aggregated into a single one: It makes it easy to separate the non-CDI API subset and use it if CDI isn't present.

On the other hand, there's a single disadvantage: Complexity, because having 2 packages instead of one may be confusing to users who want to use the CDI-based API.

I'd run a poll about this. It's more a matter of taste and what we want to focus on. I'd personally prefer simplicity and put everything in a single package, because I think that focus in users and easy adoption is more important than focus on spec creators (us) or spec implementors (vendors).

--Ondrej

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

[Kevin Sutter]

Emily,
I think Config 1.0 is first out of the chute, so you get to set the precedence.  This has been a good conversation and you're coming to a group decision (or compromise).  Go for it.  Future specs which utility the CDI programming model can follow your model.

Thanks, Kevin

[Ken Finnigan]

Right now I don't think we need explicit conventions, we can leave it up to each spec to agree how they want to do the sub package naming

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/2daf9dc5-5654-4cbe-93a1-8e676b5df483%40googlegroups.com.

[John D. Ament]

I agree with Ken, and actually take issue with the fact that this thread leans towards not using inject, but apparently inject has become our standard as per https://wiki.eclipse.org/MicroProfile/ContributingGuidelines .

John

[Ondrej Mihályi]

I wouldn't treat anything in the wiki as a dogma, especially as we don't yet have an agreement here. I don't think it was wise to put the guideline on the wiki at this stage.

Personally, I would add an alternative option to leave CDI-related parts of the API in the base package so that spec designers can decide what fits for them. Some specs might be really small and it wouldn't make sense to split the API into 2 parts, some will be bigger and it would make sense to separate CDI-based API. If we take Config spec as an example, it even makes sense to move some non-CDI parts, which are unlikely to be used with CDI, into a new package to go out of the way when using the CDI programming model. But it's not necessary, because the API itslef is not very big.

So I suggest that a spec can choose one of:

 - placing all the API into the same packages (not making distinction between CDI and non-CDI API)

 - placing CDI API into an "inject" subpackage, while all the rest is in the main package

It makes people happy, and it's still easy to use and understand for API consumers (developers). Much easier than Java EE now, when some CDI-related API is in an "inject" package (JSR 330 and CDI), some is in the top level package (JTA @Transactional) and some is mixed with other classes even in a subpackage (JSF @ViewScoped).

In the spirit of "Let's build consensus and freedom of choice instead of dogmas".

--Ondrej

[Kevin Sutter]

I was just talking with Emily about this...  We shouldn't be documenting "dogmas" before they are agreed to.  In this particular case about the CDI package names, there is a healthy discussion and we should figure out an appropriate compromise.

On the other hand, some of the information on our wiki is what I would call "lessons learned".  For example, I just updated our wiki with a bunch of information about the IP review process.  We didn't vote on it or anything, but I didn't want to lose the information in case the "proverbial beer truck" comes along this evening...  :-)

We're all just trying to make progress.

Thanks, Kevin

--
You received this message because you are subscribed to a topic in the Google Groups "MicroProfile" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/microprofile/3Pdk1gRlVnQ/unsubscribe.
To unsubscribe from this group and all its topics, send an email to microprofile+unsubscribe@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/e24781d0-9f11-4d4b-91c2-4a4ee81c764a%40googlegroups.com.