With that out of the way, let's continue our journey of understanding Icicle. Click the next button.

@PostConstruct

The PostConstruct annotation can be used on methods, to turn them into, well a secondary constructor.

These PostConstruct methods will only be called after the @Bean methods have been handled, and the setters have been auto-wired, but before the bean is registered.

Setter Auto-Wiring

There are some cases when you don't want to auto-wire only via constructors. For this exact purpose, we have introduced setter autowiring. Just create a setter and put @Autowired on top of it.

@Service
@Qualifier("secondImpl")
public class DemoServiceImpl implements DemoService {
    
    @Autowired
    public void setterAutowiring(OtherService service, DemoService defaultImplementation) {
        [...]
    }
}

Qualifiers

Remember, when we told you, that services could only have one implementation? Well, that was kind of a lie, we're sorry.

In order to achieve multiple implementations of the same service, you need to meet the @Qualifier annotation. Using it is pretty straightforward:

1. Apply it to the implementation

2. Give it a qualifier (aka. name)

3. When you auto-wire, apply the same annotation, with the same qualifier

Let us show you an example. Imagine that we have a service called DemoService, and we have 2 implementations for it:

public class ServiceUser {
    public ServiceUser(@Qualifier("secondImpl") DemoService second,
                        DemoService default) {
        [...]
    }
}

@Service
public class DefaultDemoService implements DemoService {
    [...]
}

@Service
@Qualifier("secondImpl")
public class OtherDemoService implements DemoService {
    [...]
}

Value Modifiers

Modifiers can be used to modify a value passed to a method at runtime using different logic. These modifiers are enabled via our proxy. But let an example speak for itself:

@ModifiersActive
public void test(@DefaultValue("N/A") String input) {
    // If the supplied input is null, the N/A will be printed, otherwise the value passed.
    System.out.println(input);
}

The implementation of this modifier is:

@MethodValueModifier(DefaultValue.class)
public class DefaultValueHandler implements ValueModifier {

    @Override
    public Object modify(Object input, Parameter parameter) {
        return input == null ? parameter.getAnnotation(DefaultValue.class).value() : input;
    }
}

@Primary marked beans

Oh. This section is still waiting to be written...

Providing multi-language support is vital for a successful plugin. Icicle provides an easy-to-use system with a built-in script language similar to Excel's.

Localization is done through the TranslationService.

Setting up StringProviders

StringProviders are the ones that provide the TranslationService with a string for a key from a file. With this abstraction, the developers can implement any kind of source they can think of, be it a simple file-based one, or maybe a remote solution.

Built-in solutions are the following:

• FileStringProvider --> Used for switching between multiple LanguageFiles

If you want to set up your own, do it like this:

public class MyStringProvider implements TranslationStringProvider {

    @Override
    public String get(String language, String key, String defaultValue) {
        // We recommend automatically setting the defaultValue at the key, if your
        // source does not contain a key. We also recommend returning the defaultValue here as well
        // although it should be handled in the TransltionService.
        return defaultValue;
    }
}

Setting up LanguageProviders

LanguageProviders are the ones responsible for providing a language code for a Player. Sources can be databases, geolocation, or just a fallback fixed language.

If you want to use the built-in providers, they are the following:

• ConstantLanguageProvider --> Always returns a pre-set language (used as fallback)

• PlayerLanguageGeoProvider --> returning language-based of geolocation (experimental, relies on external API!!!)

• Planned: DatabaseLanguageProvider

If you've decided you want a custom implementation, you can do so like this:

public class MyLanguageProvider implements LanguageProvider {
    @Override
    public String getLanguage(Object key) {
        // key is an object due to multi-environment support.
        // In Bukkit environments it is Player, but we recommend
        // writing an instanceof check just in case
        return "returning language code, ex.: en, de, hu";
    }
}

Using the TranslationService

The TranslationService must be auto-wired. By default - if no providers have been set up - it will use "en" as the language, and will only use the default values.

When first getting keys, the service will automatically append the default values to a translation file of choice (StringProvider must be set up for this).

Advanced Usage - String Code

StringCode is a special Excel formula-like script language, that provides translators with the ability to write logic inside a string, therefore making language-specific tasks easier.

You have {IF(EQ(amount, 1), IF(SW(item, 'a', 'e', 'i', 'o', 'u'),'an','a'),amount)} {item}{IF(GT(amount, 1), 's', '')}.

The following table shows all the functions you can use & their purpose.

Icicle is a Spring inspired framework designed for Bukkit/Spigot plugin development. It's a new way of thinking about plugin development, and not worrying about the complex systems you have to write for many hours straight.

The aim of this project is to aid you in every single part of plugin development, from basic commands to advanced protocol mechanics.

Learning the Fundamentals

• If you're already familiar with the concept of beans, or with Spring, then you will have no time picking up Icicle's style.

• If you have never heard of the things above, then don't feel disqualified. In this documentation, we will explain everything in a nutshell, so that you will understand the "weird terms" we will reference/rely on.

We've split the documentation into sections. These sections include the complete guide of separate modules, how to extend Icicle, etc. However, if you're new to Icicle (or have no idea about Spring either) we strongly recommend starting with the basics under Icicle Basics.

Create your first Icicle application

Create your first Icicle application very easily.

Setting up your development environment

To help your productivity skyrocket, we've decided to make our own development tools, with many in mind for the future.

Currently, our only development tool is our own Gradle Plugin, but don't let this little number fool you, this addon for Gradle will help you more than you can imagine, but let's dive into it further!

$ mkdir demo
$ cd demo

$ gradle init

Select type of project to generate:
  1: basic
  2: application
  3: library
  4: Gradle plugin
Enter selection (default: basic) [1..4] 2

Select implementation language:
  1: C++
  2: Groovy
  3: Java
  4: Kotlin
  5: Scala
  6: Swift
Enter selection (default: Java) [1..6] 3

Split functionality across multiple subprojects?:
  1: no - only one application project
  2: yes - application and library projects
Enter selection (default: no - only one application project) [1..2] 1

Select build script DSL:
  1: Groovy
  2: Kotlin
Enter selection (default: Groovy) [1..2] 2

Generate build using new APIs and behavior(default: no) [yes, no] yes

Select test framework:
  1: JUnit 4
  2: TestNG
  3: Spock
  4: JUnit Jupiter
Enter selection (default: JUnit Jupiter) [1..4] 1

Project name (default: demo):
Source package (default: demo):

$ nano settings.gradle.kts

pluginManagement {
    repositories {
        gradlePluginPortal() // Default plugin portal so everything still works.
        maven { // Custom repository so you can access the icicle plugin.
            url = uri("https://mvn.iceyleagons.net/snapshots/")
            name = "Igloo Snapshots"
        }
    }
}

id("net.iceyleagons.icicle-gradle") version "1.5-SNAPSHOT"

icicle {
    name = "Demo project"
    version = project.version.toString() // or anything that's a string
    description = "This is a short description for a small project"
    developers = listOf("me")
}

The bean system is the heart of this entire framework (just like in Spring). It is the one responsible for creating your classes automatically, auto-wiring them in the necessary places, and responsible for tying everything together into a cozy ecosystem.

Prepare yourself for a load of "bad words", that may not make sense. This is a very technical page, but you have to endure it because this is the base of the framework.

But what is a bean?

According to the Java white paper

It is a reusable software component. A bean encapsulates many objects into one object so that we can access this object from multiple places. Moreover, it provides easy maintenance.

In our framework, beans are the objects that form the backbone of your application and that are managed by Icicle's IoC (Inversion of Control) container/system. A bean is an object that is instantiated, assembled, and otherwise managed by Icicle behind the scenes.

In our implementation, the IoC is basically the AbstractIcicleApplication, but the actual logic is mostly handled by the BeanRegistry and the BeanManager.

Great, now that you've got a somewhat good idea about beans, let's dive deeper.

What is Dependency Injection?

Dependency injection is a pattern we can use to implement IoC, where the implementation is setting an object's dependencies behind the scenes, automatically. It also resolves many issues like unresolvable dependencies or circular dependencies.

Connecting objects with other objects, or “injecting” objects into other objects, is done by an "assembler" rather than by the objects themselves. You can think of the job of this system as the Linker in C++ for example, but this is a very cruel comparison.

DI in practice

Let's look at an easy example: you have a manager that requires JavaPlugin to run.

@Service
public class PlayerManagerImpl implements PlayerManager {

    private final JavaPlugin plugin;

    @Autowired
    public PlayerManagerImpl(JavaPlugin plugin) {
        this.plugin = plugin;        
    }
}

public class PlayerManagerImpl implements PlayerManager {

    private final JavaPlugin plugin;

    public PlayerManagerImpl(JavaPlugin plugin) {
        this.plugin = plugin;        
    }
}

public class MyPlugin extends JavaPlugin {
    private PlayerManager playerManager;
    
    @Override
    public void onEnable() {
        this.playerManager = PlayerManagerImpl(this);
    }
}

Types of Beans

As in the example, we've introduced a thing called @Service, but what is it, you may ask? Well, in this section you will learn about all the types of beans, and how they're related to one another.

Every bean is basically a subtype of @AutoCreate (for the Spring guys, it's basically an equivalent of @Component). Later on different auto-create handlers will add different functionality to them.

So, without further ado, let's look at all the bean types that are by default in the core module:

• @AutoCreate - The most basic bean type, it only provides auto-creation, management, and dependency injection.

• @Service - A slightly advanced bean. You will probably use this the most. Other than the basic functionalities @AutoCreate provides, this also allows you to auto-wire the bean with all of their interfaces. However, an interface (basically the service) can only have one implementation (the actual class you put the @Service annotation on). If multiple implementations exist for the same service, you will get an error. (If I had to compare it to something, it would be like the fact that you cannot have the same class names in a package).

• @GlobalService - Basically the same as @Service, but the implementations also get registered into the GlobalServiceProvider (in Bukkit environments to Bukkit's ServicesManager)

• @Config - Reserved for configurations, learn more about them here.

• @ConfigurationDriver - Drivers for config types

• @MethodValueModifier - Modifier handlers

• @MethodAdviceHandler - Beans that handle the registration of Advice to the ByteBuddy proxy used by the BeanManager.

• @MethodInterceptorHandler - Beans that handle the registration of Interceptors to the ByteBuddy proxy used by the BeanManager.

• @AnnotationHandler - Beans that specialize in the customization part of the framework. They are what you will use to create new annotations and bean types. (They have 2 sub-types, but we're going to meet them later on, so no need to rush their introduction)

Remember, these bean types are the default in the core, modules can register their own, and you'll meet these specific sub-types in their designated module guide section.

Now we're stepping into the more technical side of Icicle here.

As we've discussed before, we've designed Icicle with customization and expandability in mind. In this section, you'll learn how you can add your own annotations to the framework etc.

Icicle provides an easy way for multi-file configurations. Our solution also allows you to explain the different configuration fields with comments.

When you create a config or add a new field to an already existing config, Icicle will create the config file if necessary and updates the default values if needed.

Default values are taken from the field's default values set by you in the class. When the default value and the config set value are different, we'll inject the new value into the field. Basically from now on the contents of the config file controls the values of the fields inside the config bean.

Let's create a config file!

Creating a simple config file is as easy as:

@Config(value = "config.yml", headerLines = {"You can even add headers!"})
public class MyConfig implements Configuration {

    @ConfigField("settings.prefix")
    @ConfigComment("Change the prefix of the demo.")
    public String prefix = "DefaultPrefix";

    @ConfigField("settings.auto-update")
    public boolean autoUpdate = true;                
}

This code will result in the following file:

# You can even add headers!

settings:
  prefix: DefaultPrefix # Change the prefix of the demo.
  auto-update: true

Accessing values of a config

Accessing configuration values can be done in 2 ways.

• One is auto-wiring the whole config, and accessing it via the fields

• You can auto wire specific values and not the whole config, however, with this, you lose the ability to change or reload those values.

Let's take a look at both of them

@Service
public class UpdaterServiceImpl implements UpdaterService {

    private boolean autoUpdate;

    @Autowired
    public UpdaterServiceImpl(MyConfig config) {
        this.autoUpdate = (boolean) config.get("settings.prefix");     
    }
}

@Service
public class UpdaterServiceImpl implements UpdaterService {

    private boolean autoUpdate;

    @Autowired
    public UpdaterServiceImpl(@Property("settings.prefix") boolean autoUpdate) {
        this.autoUpdate = autoUpdate;  
    }
}

With that being said, you now know the configuration system of Icicle. It is easy, isn't it? Let's move forward, and see, how you can make your plugins accessible in many languages!

Icicle's functionalities are separated into their respective modules. We've done this, so you only get what you really need.

These addons can be accessed via a simple dependency notation in the dependency manager of your choice, but we highly recommend using our Gradle Plugin (you've learned about it here).

Adding modules to your project

repositories {
    igloo() // This is required for ALL first party addons,
            // as they are hosted on our m2.
}

dependencies {
    icicle("nms:1.0-SNAPSHOT") // This will add the NMS addon with the
                               // version 1.0-SNAPSHOT.

    // icicle() can also be called without any parameters.
    // In that case, it'll add the icicle-core dependency into your project.
    // Example: icicle()

    // icicle() can be called without a version provided.
    // In this case, it should fetch the latest version and download that.
    // Example: icicle("nms")
}

dependencies {
    addon("com.example:real-addon:1.0-SNAPSHOT") // This will add the
                                                 // real-addon from the
                                                 // creator example.com with
                                                 // the version 1.0-SNAPSHOT.
}

dependencies:
    # If your addon is third party, then proceed as normal.
    - "com.example:real-addon:1.0-SNAPSHOT" # Everything is necessary here.
    
    # If your addon is first party, then the syntax is
    # "net.iceyleagons:icicle-addon-<addon name>:<addon version>
    - "net.iceyleagons:icicle-addon-nms:1.0-SNAPSHOT" # Once again,
                                                      # everything is
                                                      # necessary.

Modules in the Documentation

Modules are their own story, and most of them are so complex, they deserve their own sections in this documentation:

1. Commands System

Choose your modules

Oh, so you're not here for the juicy Minecraft-specific stuff, but you want access to the basic functionalities of Icicle in your environment of choice? Well, you're on the right page!

Before we go much further, we recommend you check out this list, which contains all the ports of Icicle in different environments:

That's out of the way let's begin:

Icicle Documentation

Latest Icicle version: N/A Documentation effective from: N/A

------------------------------------------------

Welcome to the official Icicle guide! Whether you came here to learn Icicle from scratch, or you just want to understand a specific module, we hope this guide will be useful for you.

Before you go further, we ask you, to rate the pages of these guides, so we can get a clear idea of what is unclear, and what needs work. You can do it at the bottom of the pages via these 3 simple buttons:

Lastly, we wanna thank GitBook for providing us with an OpenSource License and making this documentation possible.

With that out of the way, you can continue to: Getting Started.

FAQ

Hesitant to use Icicle, or you simply have questions regarding it? Before asking us on Discord, please, be sure to read through this, as we get these questions a lot.

Is Icicle easy to learn?

If you're coming from a Spring background, or you have used dependency injection (beans) before, then you will pick up Icicle very easily.

If all of these sound foreign, then don't feel disqualified. After you've learned the basics, you will adjust to Icicle no-time.

Is Icicle free?

Yes, our goal is to help every plugin developer in the world, and let's face it: everyone hates paywalls.

Will it affect my server's performance?

No, but it may prolong server loading.

Even though Icicle is a complex system, all the time-consuming parts (scanning, registering) are done at startup - when all the other plugins & worlds load.

Do sever owners need to install Icicle?

Yes, every server owner who utilizes Icicle-based plugins needs to install Icicle in the server's plugin directory.

This is so, that all the magic is contained in one place, and will not be unnecessarily duplicated (therefore saving precious memory and storage)

Can I donate?

We currently do not have any ways to accept donations, but we're planning to set up a Ko-Fi or Patreon page.

Can I contribute?

Of course, you can! Open-source projects are all about the community. This generosity of others is what enables Icicle to stay up-to-date with all the developer needs. Please be sure to read our Contribution Guidelines, before contributing.

Documentation Maintainers

• G4be_

• TOTHTOMI