|
| 1 | +--- |
| 2 | +title: 'Java quickstart' |
| 3 | +slug: '/getting_started/scripts_quickstart/java' |
| 4 | +--- |
| 5 | + |
| 6 | +import DocCard from '@site/src/components/DocCard'; |
| 7 | + |
| 8 | +# Java quickstart |
| 9 | + |
| 10 | +In this quick start guide, we will write our first script in [Java](https://www.java.com/). |
| 11 | + |
| 12 | + |
| 13 | + |
| 14 | +This tutorial covers how to create a simple script through Windmill web IDE. See the dedicated page to [develop scripts locally](../../../advanced/4_local_development/index.mdx). |
| 15 | + |
| 16 | +<div className="grid grid-cols-2 gap-6 mb-4"> |
| 17 | + <DocCard |
| 18 | + title="Local development" |
| 19 | + description="Develop from various environments such as your terminal, VS Code, and JetBrains IDEs." |
| 20 | + href="/docs/advanced/local_development" |
| 21 | + /> |
| 22 | +</div> |
| 23 | + |
| 24 | +Scripts are the basic building blocks in Windmill. They can be [run and scheduled](../../8_triggers/index.mdx) as standalone, chained together to create [Flows](../../../flows/1_flow_editor.mdx) or displayed with a personalized User Interface as [Apps](../../7_apps_quickstart/index.mdx). |
| 25 | + |
| 26 | +<div className="grid grid-cols-2 gap-6 mb-4"> |
| 27 | + <DocCard |
| 28 | + title="Script editor" |
| 29 | + description="All the details on scripts." |
| 30 | + href="/docs/script_editor" |
| 31 | + /> |
| 32 | + <DocCard |
| 33 | + title="Triggers" |
| 34 | + description="Trigger scripts and flows on-demand, by schedule or on external events." |
| 35 | + href="/docs/getting_started/triggers" |
| 36 | + /> |
| 37 | +</div> |
| 38 | + |
| 39 | +Scripts consist of 2 parts: |
| 40 | + |
| 41 | +- [Code](#code): for Java scripts, it must have at least a **public** static main method inside a Main class. |
| 42 | +- [Settings](#settings): settings & metadata about the Script such as its path, summary, description, [jsonschema](../../../core_concepts/13_json_schema_and_parsing/index.mdx) of its inputs (inferred from its signature). |
| 43 | + |
| 44 | + |
| 45 | +From the Home page, click `+Script`. This will take you to the first step of script creation: Metadata. |
| 46 | + |
| 47 | +## Settings |
| 48 | + |
| 49 | + |
| 50 | + |
| 51 | +As part of the [settings](../../../script_editor/settings.mdx) menu, each script has metadata associated with it, enabling it to be defined and configured in depth. |
| 52 | + |
| 53 | +- **Path** is the Script's unique identifier that consists of the |
| 54 | + [script's owner](../../../core_concepts/16_roles_and_permissions/index.mdx), and the script's name. |
| 55 | + The owner can be either a user, or a group ([folder](../../../core_concepts/8_groups_and_folders/index.mdx#folders)). |
| 56 | +- **Summary** (optional) is a short, human-readable summary of the Script. It |
| 57 | + will be displayed as a title across Windmill. If omitted, the UI will use the `path` by |
| 58 | + default. |
| 59 | +- **Language** of the script. |
| 60 | +- **Description** is where you can give instructions through the [auto-generated UI](../../../core_concepts/6_auto_generated_uis/index.mdx) |
| 61 | + to users on how to run your Script. It supports markdown. |
| 62 | +- **Script kind**: Action (by default), [Trigger](../../../flows/10_flow_trigger.mdx), [Approval](../../../flows/11_flow_approval.mdx) or [Error handler](../../../flows/7_flow_error_handler.md). This acts as a tag to filter appropriate scripts from the [flow editor](../../6_flows_quickstart/index.mdx). |
| 63 | + |
| 64 | +This menu also has additional settings on [Runtime](../../../script_editor/settings.mdx#runtime), [Generated UI](#generated-ui) and [Triggers](../../../script_editor/settings.mdx#triggers). |
| 65 | + |
| 66 | +<div className="grid grid-cols-2 gap-6 mb-4"> |
| 67 | + <DocCard |
| 68 | + title="Settings" |
| 69 | + description="Each script has metadata & settings associated with it, enabling it to be defined and configured in depth." |
| 70 | + href="/docs/script_editor/settings" |
| 71 | + /> |
| 72 | +</div> |
| 73 | + |
| 74 | +Now click on the code editor on the left side. |
| 75 | + |
| 76 | +## Code |
| 77 | + |
| 78 | +Windmill provides an online editor to work on your Scripts. The left-side is |
| 79 | +the editor itself. The right-side [previews the UI](../../../core_concepts/6_auto_generated_uis/index.mdx) that Windmill will |
| 80 | +generate from the Script's signature - this will be visible to the users of the |
| 81 | +Script. You can preview that UI, provide input values, and [test your script](#instant-preview--testing) there. |
| 82 | + |
| 83 | + |
| 84 | + |
| 85 | +<div className="grid grid-cols-2 gap-6 mb-4"> |
| 86 | + <DocCard |
| 87 | + title="Code editor" |
| 88 | + description="The code editor is Windmill's integrated development environment." |
| 89 | + href="/docs/code_editor" |
| 90 | + /> |
| 91 | + <DocCard |
| 92 | + title="Auto-generated UIs" |
| 93 | + description="Windmill creates auto-generated user interfaces for scripts and flows based on their parameters." |
| 94 | + href="/docs/core_concepts/auto_generated_uis" |
| 95 | + /> |
| 96 | +</div> |
| 97 | + |
| 98 | +As we picked `Java` for this example, Windmill provided some |
| 99 | +boilerplate. Let's take a look: |
| 100 | + |
| 101 | +```java |
| 102 | +//requirements: |
| 103 | +//com.google.code.gson:gson:2.8.9 |
| 104 | +//com.github.ricksbrown:cowsay:1.1.0 |
| 105 | +//com.github.ricksbrown:cowsay:1.1.0 |
| 106 | + |
| 107 | +import com.google.gson.Gson; |
| 108 | +import com.google.gson.GsonBuilder; |
| 109 | +import com.github.ricksbrown.cowsay.Cowsay; |
| 110 | +import com.github.ricksbrown.cowsay.plugin.CowExecutor; |
| 111 | + |
| 112 | +public class Main { |
| 113 | + public static class Person { |
| 114 | + private String name; |
| 115 | + private int age; |
| 116 | + |
| 117 | + // Constructor |
| 118 | + public Person(String name, int age) { |
| 119 | + this.name = name; |
| 120 | + this.age = age; |
| 121 | + } |
| 122 | + } |
| 123 | + |
| 124 | + public static Object main( |
| 125 | + // Primitive |
| 126 | + int a, |
| 127 | + float b, |
| 128 | + // Objects |
| 129 | + Integer age, |
| 130 | + Float d, |
| 131 | + Object e, |
| 132 | + String name, |
| 133 | + // Lists |
| 134 | + String[] f |
| 135 | + // No trailing commas! |
| 136 | + ){ |
| 137 | + Gson gson = new Gson(); |
| 138 | + |
| 139 | + // Get resources |
| 140 | + var theme = Wmill.getResource("f/app_themes/theme_0"); |
| 141 | + System.out.println("Theme: " + theme); |
| 142 | + |
| 143 | + // Create a Person object |
| 144 | + Person person = new Person( (name == "") ? "Alice" : name, (age == null) ? 30 : age); |
| 145 | + |
| 146 | + // Serialize the Person object to JSON |
| 147 | + String json = gson.toJson(person); |
| 148 | + System.out.println("Serialized JSON: " + json); |
| 149 | + |
| 150 | + // Use cowsay |
| 151 | + String[] args = new String[]{"-f", "dragon", json }; |
| 152 | + String result = Cowsay.say(args); |
| 153 | + return result; |
| 154 | + } |
| 155 | +} |
| 156 | + |
| 157 | +``` |
| 158 | + |
| 159 | +In Java you need `Main` public class and public static `main` function. |
| 160 | +Return type can either be an `Object` or `void`. Any primitive java type can be automatically converted to `Object`. |
| 161 | + |
| 162 | + There are a few important things to note about the `Main`. |
| 163 | + |
| 164 | +- The arguments are used for generating |
| 165 | + 1. the [input spec](../../../core_concepts/13_json_schema_and_parsing/index.mdx) of the Script |
| 166 | + 2. the [frontend](../../../core_concepts/6_auto_generated_uis/index.mdx) that you see when running the Script as a standalone app. |
| 167 | +- Type annotations are used to generate the UI form, and help pre-validate |
| 168 | + inputs. While not mandatory, they are highly recommended. You can customize |
| 169 | + the UI in later steps (but not change the input type!). |
| 170 | + |
| 171 | +<div className="grid grid-cols-2 gap-6 mb-4"> |
| 172 | + <DocCard |
| 173 | + title="JSON schema and parsing" |
| 174 | + description="JSON Schemas are used for defining the input specification for scripts and flows, and specifying resource types." |
| 175 | + href="/docs/core_concepts/json_schema_and_parsing" |
| 176 | + /> |
| 177 | +</div> |
| 178 | + |
| 179 | +Packages can be installed through [Coursier](https://get-coursier.io/). Just add the dependencies you need at the top of the file, using the following format: |
| 180 | + |
| 181 | +```java |
| 182 | +//requirements: |
| 183 | +//groupId:artifact:Id:version |
| 184 | +//com.google.code.gson:gson:2.8.9 |
| 185 | +//com.github.ricksbrown:cowsay:1.1.0 |
| 186 | +``` |
| 187 | +It supports [Maven](https://maven.apache.org/what-is-maven.html) and [Ivy](https://ant.apache.org/ivy/) repositories. |
| 188 | + |
| 189 | +## Instant preview & testing |
| 190 | + |
| 191 | + |
| 192 | +Look at the UI preview on the right: it was updated to match the input |
| 193 | +signature. Run a test (`Ctrl` + `Enter`) to verify everything works. |
| 194 | + |
| 195 | +<video |
| 196 | + className="border-2 rounded-lg object-cover w-full h-full dark:border-gray-800" |
| 197 | + controls |
| 198 | + src="/videos/auto_g_ui_landing.mp4" |
| 199 | +/> |
| 200 | + |
| 201 | +## Generated UI |
| 202 | + |
| 203 | +From the Settings menu, the "Generated UI" tab lets you customize the script's arguments. |
| 204 | + |
| 205 | +The UI is generated from the Script's main function signature, but you can add additional constraints here. For example, we could use the `Customize property`: add a regex by clicking on `Pattern` to make sure users are providing a name with only alphanumeric characters: `^[A-Za-z0-9]+$`. Let's still allow numbers in case you are some tech billionaire's kid. |
| 206 | + |
| 207 | + |
| 208 | + |
| 209 | +<div className="grid grid-cols-2 gap-6 mb-4"> |
| 210 | + <DocCard |
| 211 | + title="Script kind" |
| 212 | + description="You can attach additional functionalities to Scripts by specializing them into specific Script kinds." |
| 213 | + href="/docs/script_editor/script_kinds" |
| 214 | + /> |
| 215 | + <DocCard |
| 216 | + title="Generated UI" |
| 217 | + description="main function's arguments can be given advanced settings that will affect the inputs' auto-generated UI and JSON Schema." |
| 218 | + href="/docs/script_editor/customize_ui" |
| 219 | + /> |
| 220 | +</div> |
| 221 | + |
| 222 | +## Run! |
| 223 | + |
| 224 | +We're done! Now let's look at what users of the script will do. Click on the [Deploy](../../../core_concepts/0_draft_and_deploy/index.mdx) button |
| 225 | +to load the script. You'll see the user input form we defined earlier. |
| 226 | + |
| 227 | +Note that Scripts are [versioned](../../../core_concepts/34_versioning/index.mdx#script-versioning) in Windmill, and |
| 228 | +each script version is uniquely identified by a hash. |
| 229 | + |
| 230 | +Fill in the input field, then hit "Run". You should see a run view, as well as |
| 231 | +your logs. All script runs are also available in the [Runs](../../../core_concepts/5_monitor_past_and_future_runs/index.mdx) menu on |
| 232 | +the left. |
| 233 | + |
| 234 | + |
| 235 | + |
| 236 | +You can also choose to [run the script from the CLI](../../../advanced/3_cli/index.mdx) with the pre-made Command-line interface call. |
| 237 | + |
| 238 | +<div className="grid grid-cols-2 gap-6 mb-4"> |
| 239 | + <DocCard |
| 240 | + title="Triggers" |
| 241 | + description="Trigger scripts and flows on-demand, by schedule or on external events." |
| 242 | + href="/docs/getting_started/triggers" |
| 243 | + /> |
| 244 | +</div> |
| 245 | + |
| 246 | +## Caching |
| 247 | + |
| 248 | +Every binary and dependency on Java is cached on disk by default. Furthermore if you use the [Distributed cache storage](../../../misc/13_s3_cache/index.mdx), it will be available to every other worker, allowing fast startup for every worker. |
| 249 | + |
| 250 | +## What's next? |
| 251 | + |
| 252 | +This script is a minimal working example, but there's a few more steps that can be useful in a real-world use case: |
| 253 | + |
| 254 | +- Pass [variables and secrets](../../../core_concepts/2_variables_and_secrets/index.mdx) |
| 255 | + to a script. |
| 256 | +- Connect to [resources](../../../core_concepts/3_resources_and_types/index.mdx). |
| 257 | +- [Trigger that script](../../8_triggers/index.mdx) in many ways. |
| 258 | +- Compose scripts in [Flows](../../../flows/1_flow_editor.mdx) or [Apps](../../../apps/0_app_editor/index.mdx). |
| 259 | +- You can [share your scripts](../../../misc/1_share_on_hub/index.md) with the community on [Windmill Hub](https://hub.windmill.dev). Once |
| 260 | + submitted, they will be verified by moderators before becoming available to |
| 261 | + everyone right within Windmill. |
| 262 | + |
| 263 | +Scripts are immutable and there is an hash for each deployment of a given script. Scripts are never overwritten and referring to a script by path is referring to the latest deployed hash at that path. |
| 264 | + |
| 265 | +<div className="grid grid-cols-2 gap-6 mb-4"> |
| 266 | + <DocCard |
| 267 | + title="Versioning" |
| 268 | + description="Scripts, when deployed, can have a parent script identified by its hash." |
| 269 | + href="/docs/core_concepts/versioning#script-versioning" |
| 270 | + /> |
| 271 | +</div> |
| 272 | + |
| 273 | +For each script, a UI is autogenerated from the jsonchema inferred from the script signature, and can be customized further as standalone or embedded into rich UIs using the [App builder](../../7_apps_quickstart/index.mdx). |
| 274 | + |
| 275 | +<div className="grid grid-cols-2 gap-6 mb-4"> |
| 276 | + <DocCard |
| 277 | + title="Auto-generated UIs" |
| 278 | + description="Windmill creates auto-generated user interfaces for scripts and flows based on their parameters." |
| 279 | + href="/docs/core_concepts/auto_generated_uis" |
| 280 | + /> |
| 281 | + <DocCard |
| 282 | + title="Generated UI" |
| 283 | + description="main function's arguments can be given advanced settings that will affect the inputs' auto-generated UI and JSON Schema." |
| 284 | + href="/docs/script_editor/customize_ui" |
| 285 | + /> |
| 286 | +</div> |
| 287 | + |
| 288 | +In addition to the UI, sync and async [webhooks](../../../core_concepts/4_webhooks/index.mdx) are generated for each deployment. |
| 289 | + |
| 290 | +<div className="grid grid-cols-2 gap-6 mb-4"> |
| 291 | + <DocCard |
| 292 | + title="Webhooks" |
| 293 | + description="Trigger scripts and flows from webhooks." |
| 294 | + href="/docs/core_concepts/webhooks" |
| 295 | + /> |
| 296 | +</div> |
0 commit comments