Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

CloudNet v4: API User-Documentation/Examples #1287

Open
1 task done
DasBabyPixel opened this issue Aug 16, 2023 · 7 comments
Open
1 task done

CloudNet v4: API User-Documentation/Examples #1287

DasBabyPixel opened this issue Aug 16, 2023 · 7 comments
Labels
t: feature request A request of a feature someone wants to see in a future release. t: tracking Tracking issue for an experimental or scheduled for removal api. v: 4.X This pull should be included in the 4.0 release

Comments

@DasBabyPixel
Copy link
Contributor

Describe the new feature

Add a dedicated examples project like there is in v3. It'd be a great help to have different examples on how to use the new dependency injection and how to find the classes you need, now that we do not have a central Driver that has all the methods.

Why do you need this feature?

It is a great help to all developers trying to migrate to v4

Alternatives

Open to other suggestions, otherwise no alternatives

Other

No response

Issue uniqueness

  • Yes, this issue is unique. There are no similar issues.
@DasBabyPixel DasBabyPixel added s: needs triage Issue waiting for triage t: feature request A request of a feature someone wants to see in a future release. labels Aug 16, 2023
@derklaro
Copy link
Member

It's planned when the api is considered stable. As there are still some changes planned, it doesn't make much sense to write full guides just to change them again accordingly.
I will keep this open - if someone has suggestions or even code examples that we should put into the documentation feel free to post them here 😄

@derklaro derklaro added v: 4.X This pull should be included in the 4.0 release and removed s: needs triage Issue waiting for triage labels Aug 17, 2023
@derklaro derklaro pinned this issue Aug 17, 2023
@DasBabyPixel
Copy link
Contributor Author

Any forecast on how long it is going to take until there is a release?

@PC1up

This comment was marked as outdated.

@DasBabyPixel
Copy link
Contributor Author

This thread is about examples for CloudNet 4.
Anyone looking for examples for CloudNet 3 can find them here.
(There are also "official" examples for the permission system, but thanks for trying to provide examples 👍 )

As far as I know the cloud permission system is going to be removed. Anyone actively using it might want to migrate to luckperms

@derklaro derklaro changed the title API Examples CloudNet v4: API User-Documentation/Examples Sep 16, 2023
@derklaro derklaro added the t: tracking Tracking issue for an experimental or scheduled for removal api. label Sep 16, 2023
@CN-Dragon
Copy link

I have not used dependency injection before, and I hope to provide an example as soon as possible

@DasBabyPixel
Copy link
Contributor Author

A quick summary for most use cases:
If you want to develop a CN-Module, you can acquire object instances in the methods annotated with @ModuleTask.
If you want to develop a server plugin that uses CN api, see examples later in this post
This gives you access to pretty much everything that used to be in CloudNetDriver

@ModuleTask(lifecycle = ModuleLifeCycle.STARTED)
public void start(@Name("module") InjectionLayer<SpecifiedInjector> injectionLayer, ComponentInfo componentInfo, DatabaseProvider databaseProvider) {
}

You can add as many parameters as you need.
The first parameter in this example is the InjectionLayer for the module. (Parameter can also be omitted if not required)
This InjectionLayer is the thing behind the scenes that gets you the instances.
If you want an instance and you do not have the option of getting it in a @ModuleTask method, you can use the InjectionLayer to do so:

DatabaseProvider databaseProvider = injectionLayer.instance(DatabaseProvider.class)

The InjectionLayer with @name("module") is an InjectionLayer specifically for YOUR module. It inherits from the default CN InjectionLayers (ext).
These default InjectionLayers are InjectionLayer.ext() and InjectionLayer.boot(). ext inherits from boot and is meant for extension use cases.
Because ext inherits from boot, the InjectionLayer of your module implicitly inherits from boot. (module < ext < boot)
All the object instances you usually need are installed in boot.
If you want access from a server plugin (and not a CN-module), you can use these InjectionLayers to get instances:
InjectionLayer.boot().instance(DatabaseProvider.class)

Services I have used so far

  • ServiceInfoHolder
  • EventManager
  • DatabaseProvider
  • ComponentInfo
  • ServiceTaskProvider
  • TemplateStorageProvider
  • GroupConfigurationProvider
  • ServiceRegistry
  • BridgeServiceHelper

The PlayerManager is bridge specific and thus hidden behind the ServicesRegistry:
Example for use inside bukkit plugin:

private final PlayerManager playerManager = InjectionLayer.boot().instance(ServiceRegistry.class).firstProvider(PlayerManager.class);

Little more advanced
You can install custom Bindings (basically object instances/object instance suppliers) into any InjectionLayer.
This can be done by using

injectionLayer.install(BindingBuilder.create().bind(ProviderInterface.class).toInstance(new ProviderImplementation()))

You can also inject object instances in constructors, to understand how that works I recommend taking a closer look at existing CloudNet modules like bridge, which are good examples of recommended usage. These modules take it a step further and do not constructors, they instead let the DI framework construct all the objects. They only say: "Hey, gimme an instance of XYZ".

If you need more information on DI, I can recommend the jakarta specs and the Aerogel github README
JSR 330 is also an option, but IMO thats the worse documentation

This should pretty much cover all basic usage.

@derklaro correct me if I'm wrong about anything here pls

@CN-Dragon
Copy link

very think @

A quick summary for most use cases: If you want to develop a CN-Module, you can acquire object instances in the methods annotated with @ModuleTask. If you want to develop a server plugin that uses CN api, see examples later in this post This gives you access to pretty much everything that used to be in CloudNetDriver

@ModuleTask(lifecycle = ModuleLifeCycle.STARTED)
public void start(@Name("module") InjectionLayer<SpecifiedInjector> injectionLayer, ComponentInfo componentInfo, DatabaseProvider databaseProvider) {
}

You can add as many parameters as you need. The first parameter in this example is the InjectionLayer for the module. (Parameter can also be omitted if not required) This InjectionLayer is the thing behind the scenes that gets you the instances. If you want an instance and you do not have the option of getting it in a @ModuleTask method, you can use the InjectionLayer to do so:

DatabaseProvider databaseProvider = injectionLayer.instance(DatabaseProvider.class)

The InjectionLayer with @name("module") is an InjectionLayer specifically for YOUR module. It inherits from the default CN InjectionLayers (). These default InjectionLayers are and . inherits from and is meant for extension use cases. Because inherits from , the InjectionLayer of your module implicitly inherits from . ( < < ) All the object instances you usually need are installed in . If you want access from a server plugin (and not a CN-module), you can use these InjectionLayers to get instances:ext``InjectionLayer.ext()``InjectionLayer.boot()``ext``boot``ext``boot``boot``module``ext``boot``boot InjectionLayer.boot().instance(DatabaseProvider.class)

Services I have used so far

  • ServiceInfoHolder
  • EventManager
  • DatabaseProvider
  • ComponentInfo
  • ServiceTaskProvider
  • TemplateStorageProvider
  • GroupConfigurationProvider
  • ServiceRegistry
  • BridgeServiceHelper

The PlayerManager is specific and thus hidden behind the ServicesRegistry: Example for use inside bukkit plugin:bridge

private final PlayerManager playerManager = InjectionLayer.boot().instance(ServiceRegistry.class).firstProvider(PlayerManager.class);

Little more advanced You can install custom Bindings (basically object instances/object instance suppliers) into any InjectionLayer. This can be done by using

injectionLayer.install(BindingBuilder.create().bind(ProviderInterface.class).toInstance(new ProviderImplementation()))

You can also inject object instances in constructors, to understand how that works I recommend taking a closer look at existing CloudNet modules like , which are good examples of recommended usage. These modules take it a step further and do not constructors, they instead let the DI framework construct all the objects. They only say: "Hey, gimme an instance of XYZ".bridge

If you need more information on DI, I can recommend the jakarta specs and the Aerogel github README JSR 330 is also an option, but IMO thats the worse documentation

This should pretty much cover all basic usage.

@derklaro correct me if I'm wrong about anything here pls

very think u !!!!!!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
t: feature request A request of a feature someone wants to see in a future release. t: tracking Tracking issue for an experimental or scheduled for removal api. v: 4.X This pull should be included in the 4.0 release
Projects
None yet
Development

No branches or pull requests

4 participants