Syntax Registry concept

Development
#13

I would go for List<Syntax> SyntaxProvider#getSyntaxes(). I don’t really see the point of implementing javax.inject.Provider since it would not be used that way and I prefer a more explicit method name.

#14

The reason is to stay with best practices and use well known existing interfaces instead of reinventing the wheel. Always best (since it means future code readers will understand it better since it’s well known and documented beyond xwiki)

#15

This is not true actually. Anyone will be able to use it that way if they want it. some code using Guice (for ex), or CDI (another ex), can use it. It’s meant for that, to return a syntax.

#16

That’s true only if we get those syntaxes through the Provider role, but I doubt that’s what we want here. I feel a more typed API would be safer/nicer.

#17

There’s no need for a typed method name since it’s already contained in the class name. It’s actually creating a duplication. SyntaxProvider = provides syntax(es).

#18

ok, can do, but the name would be plural then I guess: registerSyntaxes(Syntax...). It’s just slightly more painful when you have a List<Syntax>since you need create an array from it.

#19

It’s not only about the method name, if you implement Provider you return an Object and since there is no point in using this through the Provider API I really don’t think implementing it is a good idea. People should use the registry to get syntaxes. We never said that a best practice for any component which want to provide stuff is to implement Provider.

#20

You return a List<Syntax>: Provider (Java EE 6 )

For example:

...
public class SyntaxProvider implements Provider<List<Syntax>>
{
    List<Syntax> get() {...}
}

BTW maybe it should be SyntaxesProvider instead of SyntaxProvider since we return a list.

This component will not just be for the Syntax registry. It’s a standard component that any code can call to list the syntaxes provided by a given module/component.

We never said that a best practice for any component which want to provide stuff is to implement Provider.

We do that in general since it’s about following well known java design patterns: Factory, Provider, Singleton, Builder, etc. For me Provider is almost a JDK class and I see it similar to the functional interfaces that exist in Java (Runnable and the like). I really don’t see why we would reinvent the wheel here (I don’t see a single advantage actually - the naming is not a real advantage since it’s already in the name).

#21

After reading the thread, I’m -1 for Initializer which I agree does not convey the actual role of the class.
I don’t see the harm of using Provider since it is parametrized.
I wouldn’t object for a List<Syntax> getSyntax() method though.

#22

Your example is a bit misleading since there would not really be any SyntaxProvider intermediary class anymore, it would be more something like:

@Component
@Named("mysyntax/5.4")
public class MySyntaxProvider implements Provider<List<Syntax>>
{
    List<Syntax> get() {...}
}

I can actually think of one critical benefit of going through the Provider API: it becomes possible to implement it in all the contrib extensions without depending on a more recent version of XWiki. That was not possible with the previous proposal while contrib extensions are actually the main target of this API.

So +1 to use javax.inject.Provider<List<Syntax>> when you want to declare syntaxes that should end up in the registry.

#23

I might be wrong but I’ve the feeling that we’re mixing two usecases in the thread:

  1. we want to be able to register new syntaxes and to allow contributors to add syntaxes to the registry when they contribute to extensions
  2. we want to be able to retrieve all the syntaxes currently registered

I’m completely +1 to use a javax.inject.Provider<List<Syntax>> for usecase 2, but I find it a bit weird to use it as a way to register syntaxes for developers.
IMO it would be better to not mix those two usecases, so to have:

  1. a SyntaxRegistrator component with register/unregister methods (which could take list of syntaxes if needed)
  2. a javax.inject.Provider<List<Syntax>> if we want it which would return all syntaxes (but that could be also another method of SyntaxRegistrator IMO)
#24

For this, you would use SyntaxRegistry#getSyntaxes(). What’s wrong with that?

I may not have understood your point though.

For me what we’re discussing is only for UC1 (" 1. we want to be able to register new syntaxes and to allow contributors to add syntaxes to the registry when they contribute to extensions").

#25

Nothing wrong with that.

Well I aparently read a bit too fast the thread, since I thought the discussion with using javax.inject.Provider<List<Syntax>> was for UC1, but IMO it also shows that the name is maybe not that good.
It looks like the usual issue for naming: taking the POV of the user of the API, or the contributor of the API. Most of the time we use Provider to get something injected in our code, and in XWiki codebase we very rarely contribute to the API with a new Provider to register or declare something.

So I’d be -0 for using javax.inject.Provider<List<Syntax>> to register a new syntax, since I don’t find it natural in the context of XWiki, even if I see your point when you say that the name indicates it provides something.
I’m +1 with Marius suggestion to have a component with register/unregister methods, since I find it more explicit.

#26

So it’s not related to syntax registration. It’s a component to declare provided syntaxes by a component located in a JAR/module.

It just happens that the Syntax Registry uses that to initialize the known syntaxes, but it can be used for other use cases.

#27

hmm I must have missed this suggestion from Marius. Could you point to it? I’d like to know more since that feels like a major pain to use.

#28

talking about this.

#29

@surli from what I understand @mflorea was not suggesting to drop the providers concept. He was just commenting on having only one registerSyntax instead of several in @vmassol proposal.

#30

Yes, I replied here: Syntax Registry concept - #18 by vmassol

#31

Ok sorry for the noise, what I actually misread was the original JIRA issue, so there was actually different usecases discussed in there, I thought that the proposed Provider would be the only mechanism to register a Syntax which was the reason why I wasn’t a big fan of it. Now AFAIU it’s just another way to register it more easily.

So with that in mind ok I’m +1 with the Provider idea.

#32

Cool, we’re progressing :slight_smile: Thx