Welcome to Javatar¶
Javatar is a plugin for Sublime Text 3 and for Java development. The inspirations behind Javatar is Eclipse, the open-source Java IDE.
New to Javatar?¶
Take a look at Getting Started and become a Javatar! [1]
Table of Contents¶
Features¶
Javatar is designed to be IDE-like plugin by provides many features that help develop Java applications faster and easier.
- [S] Packages and Subpackages creation
- [S] Class (also Abstract), Interface and Enumeration snippets with package/class name auto-complete
- [S] Project/Package/Class build and run with dependencies [4]
- [S] Packages path in status bar
- [S] External libraries packages
- [S] Internal console with input supports
- [D] Organize Imports [4]
- [P] Rename/Move packages or classes [5]
- [P] .jar file export (include executable .jar) [6]
- [P] Dynamic method call auto-complete
[S] | (1, 2, 3, 4, 5, 6) Available on stable channel |
[D] | Partial available on development channel |
[P] | (1, 2, 3) Planned |
[4] | (1, 2) Organize Imports will not support classes inside dependencies except provided by Javatar Packages |
[5] | Auto-refactor is not included |
[6] | Export as executable JAR may delay after normal JAR export feature is finished |
Important Updates and Changelogs¶
From 11 Apr 2014, Javatar will not include any packages inside its package. This helps install and update Javatar faster but still maintaining default features. Javatar will automatically download and install necessary packages (Java SE) at startup since users install Javatar usually already connected to the internet.
Development Build¶
- Javatar now have its own Java parser, you can play with it via Development Section... > Parse Document (more informations about grammar on Javatar Grammar)
Stable Build¶
- Javatar now nest project settings inside “Javatar” key
- Javatar will automatically detect installed JDK and will automatic select the best one (more details on JDK Detections)
- New menu section, Javatar Settings
- New feature, Run main class. Can be accessed via Development Section... > Builds: Run Main Class (more details on Javatar Shell)
- Build now put all .class files in “bin” directory and support dependencies (more informations about dependencies in Projects Settings)
- Project/Package/Class Build improvements (now support multiple files building and error logs)
- Fix path not working properly
Screenshots¶
A picture is worth a thousand words. That is what they said...
Creating packages¶
Creating classes¶
Class operations¶
Project settings¶
Notice! The location of new packages before and after source folder has been set
Building and Running Java code¶
Getting Started¶
Welcome you, the new Javatar! I will take you through a simple project to help using Javatar faster and better suit your workspace.
This should take some time since I am going to explain everything you might need to know. But in a normal work, you would done all of this in a few minutes.
In the end of this chapter, we will see a simple application that take our input and respond to us.
If you are ready, let’s begin!
Startup¶
Javatar is designed to be ready out of the box. At startup, Javatar will load their snippets, packages and check for any available Additional Packages and later, you might see a notification display some important update messages.
If you run Javatar for the first time, it also download and install necessary packages (Java SE) for you too.
Usually, you can use Javatar right away when you open Sublime Text since most users did not start create a new class or organize imports at startup time.
Preparing Our New Project¶
To prepare our project, we need to create a folder to contains our files then open it in Sublime Text and do not forget to create src folder to store our Java source code.
First Command¶
Let’s try working with a command. First, we need to create a new package to test some Java code.
We will pressing Key+Shift+K twice to open Javatar‘s menu and select Create... > Package to open up input box.
Note
Key is Control on Windows, Super on Linux and Command on OS X.
Then type javatar.simple.demo and hit Enter or Return.
And there it is! Our first package.
But unfortunately, our package is ends up in a wrong place. We want our package to be created inside src folder. Why is that? There is a reason...
Source Folder¶
The reason that our package ends up in a wrong place because we did not set the source folder yet. What is source folder? Source Folder is, obviously, a folder which contains source code files. Since, we want our source code to be placed inside src folder. Hence, the src folder should be set as source folder as the name stated.
To set a source folder, we will run a command Set Source Folder. We will pressing Key+Shift+K twice again to open Javatar‘s menu and select Project Settings... > Set Source Folder
Then we will select src folder as we want.
Warning
Source Folder and Dependencies settings will be reset if you do not save your project.
First Class¶
After we set a source folder, it is time to recreate that package again (do not forget to remove an old one too!) but since we are going to create a class later, we will try a faster command that let’s us create both package and class at the same time.
Press Key+Shift+K twice and select Create... > Class and it will wait for us to enter a class name.
Enter javatar.simple.demo.Main and hit Enter or Return to create it.
And bam! A class is create inside a proper package path. Isn’t that great?
So, Create Package command is useless? Well, not so much. Sometimes you might need to create a package before create a class to organize packages, and later you will filled it up with a bunch of classes. And that is time when Create Package comes in.
Package Path¶
Right now, if you look at your status bar at the bottom of the window, you will notice that there is package path showing. This will changed when you switch to another tabs that is Java file, indicated which package current file is in.
Coding Time!¶
It is fun time! Let’s code a simple application that take our name and display “Hello, <Name>!”
package javatar.simple.demo;
import java.util.Scanner;
public class Main {
public static void main(String[] args) {
Scanner sc = new Scanner(System.in);
System.out.print("Hey! What's your name: ");
String name = sc.nextLine();
System.out.println("Hello, " + name + "!");
}
}
Build Our Project¶
We just done our first Java coding. Let’s build and run it!
Select Builds... > Project from the menu and wait...
If something is wrong, Javatar will show you in a new view.
Running Our Code¶
It is time to test our application. To run just select Builds... > Run Main Class and Javatar will launch our application on a new view.
If application exit properly, Javatar will show return code in a tab. But if you want to force quit an application, just close the view and an application will be terminated.
Final¶
And you just learn most parts of Javatar by now. Explore it! Try download some packages if you need!
And Happy Coding!
Commands List¶
Here is the list of commands available via Javatar‘s menu.
Reload Javatar [1]
- Builds...
- Project
- Package
- Working
- Current Class
- Run Main Class
- Calls...
- Package Name
- Subpackage Name
- Full Class Name
- Class Name
- Create...
- Package
- Abstract Class
- Class
- Enumerator
- Interface
- And your own Javatar‘s snippets
- Operations...
- Correct Class
- Project Settings...
- Dependencies...
- Add External .jar
- Add Class Folder
Set Source Folder
Set Default JDK
- Javatar Settings...
- Dependencies...
- Add External .jar
- Add Class Folder
Set Default JDK
- Packages Manager...
- Install Packages...
- List of available packages
- Uninstall Packages...
- List of installed packages
Reload and Update Packages
- Package Tools...
- Create new Javatar Packages
- Generate SHA-256 Hash
- Generate SHA-256 Hash from URL
- Convert Imports
- Development Section... [2]
- Operations: Organize Imports
- Operations: Rename Class
- Operations: Rename Package
- Parse Document
- Prettify JSON
- Testing
- Help and Support...
- Actions History
- Actions History (Custom)
- Javatar
[1] | Available in debug mode |
[2] | Available in development channel |
Note
Menu item ends with ellipsis (3 dots) indicated that menu has submenus.
Commands Categories¶
Javatar have a lot of commands to be used, show them all like Command Palette can confused and also hard to search. So, in order to help organize and search for commands easier, Javatar group all similar commands into section.
Calls¶
- Insert class or package informations such as current class path, class name or package path
- More details on Calls
Create¶
- Create a new classes or packages
- More details on Advanced Creations
Operations¶
- Do class or package operations such as organize imports, rename class or package
- More details on Operations
Project Settings [1]¶
- Adjust settings for current projects
- More details on Projects Settings
Builds¶
Javatar use its own Build System which based on default Sublime Text‘s JavaC build settings. Building classes in Javatar can be done in several ways...
Project¶
Building project will let Javatar build all Java files in your project.
Package¶
Building package will let Javatar build all Java files in current packages based on current file.
Working¶
Working is short for working Java files. This will let Javatar build all Java files currently open in current window.
Current Class¶
Building current class will let Javatar build, obviously, current Java file in current view.
Calls¶
Calls are use to insert class or package informations at cursor point. Javatar supports 4 types of calls...
Package Name¶
Return current package path
Subpackage Name¶
Return subpackage name from current package path
Full Class Name¶
Return full class path
Class Name¶
Return current class name based on class definition or file name
Advanced Creations¶
In all create related commands, all packages and classes will be created relative to current package unless specified by ~ (tilde) before package or class path. See examples below...
Input | As Package | As Class |
---|---|---|
Alpha | Package "Alpha" is created in current package | Class "Alpha" is created in current pacakge |
~Beta | Package "Beta" is created in default package | Class "Beta" is created in default pacakge |
Alpha.Beta | Package "Beta" is created in "(current package).Alpha" package | Class "Beta" is created in "(current package).Alpha" package |
~Alpha.Beta | Package "Beta" is created in "Alpha" | Class "Beta" is created in "Alpha" |
Operations¶
Operations help you do class or package, obviously, operations such as organize imports or rename class easier. Currently, Javatar has 2 operations...
Correct Class¶
Javatar will search for current package and your class name based on file name and location of current file and correct it on first class definition.
Organize Imports¶
Javatar will automatically imports all necessary packages and remove unused packages for you. This is done within 7 sub-steps.
- Javatar gathering imports informations from current file
- Javatar let’s you select a package that has the same class
- Javatar imports “default imports” and Java’s packages
- Javatar asks you to enter package name for missing classes
- Javatar asks for package name that you want to enter manually
- Javatar clear all imports in current file
- Javatar imports all packages that has been processed within step 1-4
Projects Settings¶
Project Settings section contains per-project settings.
Tip
All Javatar‘s settings can be set specifically for each project by setting it in project file instead of user preferences
Dependencies¶
Javatar support build and run project that have dependencies .jar files both global and specific projects. To add a dependency to global projects (all projects), go to Javatar Settings... > Dependencies... and select Add External .jar or Add Class Folder and Javatar will show a dialog to select a dependency you want to add. To add a dependency to current project, same as for global projects but using Project Settings... > Dependencies... menu instead.
Set Source Folder¶
As default, Javatar will specified a default package (mostly) based-on current working folder or folder contains current working file (more details on next section). Many projects might use multiple folders and some of them are not source folder. Set source folder helps solve this issue by let you select which folder to specified as Source Folder (or default package as Javatar use).
Set Default JDK¶
As default, Javatar will use global JDK (more details on JDK Detections). Set a default JDK for each project can be helpful since you might want some projects to use newer JDK version.
To set a default JDK for your project, go to Project Settings... > Set Default JDK and Javatar will show a list of JDK you have and available to use.
Default Package Detection¶
Javatar will specify default package with these steps...
- Source Folder specified in current project file (when open project)
- Project folder in current project file (when open project or folder)
- Folder contains current file (when open file)
- Specify current package as (Unknown Package)
Javatar will refuse to create packages or classes within unknown package. In this case, mostly because current file is not on the disk yet.
JDK Detections¶
At startup time, Javatar will automatically detect installed JDK in your computer and select the best one.
Here is the steps it take to select the best JDK for most projects...
- Run a checking command to see that Java has been setup as default
- Search all JDK directory in installation path (depends on your OS)
- If Java is already setup, use the default one. And set all available JDK version to settings (as your JDK settings)
- If Java is not setup yet, use the latest version that available
- If Java is not setup and there is no Java installed, Javatar will notify that you did not install Java yet
If you install Java anywhere else, you can set how Javatar search and detect JDK by setting it in Javatar‘s user preferences.
Installation¶
Package Control (Recommended)¶
Open command palette and type Install Package then type Javatar and hit Enter or Return. Package Control will automatically download, install and update for you.
“git” Command¶
Open your favourite Terminal application, browse to PACKAGES_PATH and run this command.
git clone git://github.com/spywhere/Javatar.git
Manual Install¶
Download .zip file from Javatar repository and browse to PACKAGES_PATH, extract .zip file and rename folder to Javatar, restart Sublime Text if you are currently open.
Note
PACKAGES_PATH is referred to folder which can be accessed via the Preferences > Browse Packages...
Settings¶
Settings can be accessed via the Preferences > Package Settings > Javatar from menu bar or via command palette by type Preference Javatar.
Default settings should not be modified. However, you can copy the relevant settings into Javatar‘s user settings file.
Some settings contain macro for special value such as Source Folder or Project Directory. The followings are all macro supported by Javatar...
- Available anywhere
- $project_dir
- Project Directory
- $source_folder
- Source folder
- $packages_path
- Sublime Text‘s packages path
- $sep
- Path separator. Such as “/” on Unix and “\” on Windows
- Available when open a file
- $full_class_path
- Full class path. Such as “package.subpackage.classname”
- $package
- Current package. Such as “package.subpackage”
- $class_name
- Current class name. Such as “classname”
- Available when open a file on specific context (such as build or run)
- $file
- Full path to file. Such as “/Users/home/File.java”
- $file_parent
- Full path of parent directory. Such as “/Users/home/”
- $file_name
- File name. Such as “File.java”
- $sourcepath
- Source path flag for build command (-sourcepath)
- $classpath
- Class path flag for build and run command (-classpath)
- $d
- Output path flag for build command (-d)
Note
Make sure you are quoted all path specific value to escape spaces.
Key Bindings¶
Key bindings can be accessed via the preference menu or via command palette same as settings.
Default Key Binding¶
All commands start with Key+Shift+K then follows by their shortcut key.
- Browse Commands... : Key+Shift+K
- This will open quick panel, showing you all commands available to use.
- Help and Support... : Key+Shift+H
- This will open quick panel, showing you all utilities that help solve the issue (mostly requested to do by developer).
- Builds... : Key+Shift+B
- This will open quick panel to select which build you want to perform.
- Calls... : Key+Shift+J
- This will open quick panel to select which information you want to insert.
- Operations... : Key+Shift+O
- This will open quick panel to select which operation you want to perform.
- Create new... : Key+Shift+N
- This will open quick panel, showing you all possible types to create.
- Create new package : Key+Shift+P
- This will open input panel, just like when you create a new package.
- Organize Imports : Key+Shift+I (Only on development channel)
- This will organize imports on current file.
- Project Settings : Key+Shift+. (Not available at this moment)
- This will open quick panel, showing you all settings you can adjust for current project.
- Javatar Settings : Key+Shift+, (Not available at this moment)
- This will open quick panel, showing you all settings you can adjust for global projects.
Note
Key is Control on Windows, Super on Linux and Command on OS X.
Build System¶
Javatar‘s build system use its internal shell to build your classes. Javatar build parameters are based on default Sublime Text‘s JavaC build settings. You can change the build command via Javatar settings file.
Javatar‘s build system support multi-threads building. By running multiple instance of build system to help build your class faster. You can set how many threads you want to run in Javatar‘s user preferences.
While building, Javatar will show building progress in Sublime Text‘s status bar. If it found any error, Javatar will show you a new view contains all errors and will keep on printing until building is complete. To cancel building in progress, just close an error logs view and Javatar will stop building your classes immediately.
Note
Building cannot be stopped if there is no error occurred.
Javatar Shell¶
Javatar shell is working like normal shell terminal. The difference between Javatar shell and another shells is Javatar shell will send your input by pressing Enter/Return (that give you ability to reedit your content on current line).
While Javatar shell is running, you can close the view to force quit any application that still running in the shell.
Warning
We cannot gurranteed that output or input is corrected when you are enter while Javatar shell is printing an output from the shell since Javatar shell did not set the view to read-only while printing.
Javatar Snippets¶
Javatar snippets is a dynamic snippet which will change part of the file to correspond with package path and class name. By using macros, you can specify which part of the file you want to fill the data to.
You can make your own snippets to use within Javatar by create a new file ends with .javatar
Snippet class tags (for more informations about snippet tags, see below) will be used as a type of classes which show in input panel when create a new file (%type% Name:), on error dialog (%type% %name% already exists) and in status bar when file was created (%type% %name% is created within package %package%).
Example of Javatar‘s snippets is inside Javatar‘s snippets folder (PACKAGES_PATH/Javatar/snippets or inside .sublime-packages file)
Snippet Tags¶
The following tags are used inside Javatar snippet files (*.javatar) which will be used by Javatar to display proper command to the user
- %class:*TYPE OF CLASS*%
- %description:*DESCRIPTION TO SHOW UNDER CREATION COMMAND*%
Usage of snippet tags in action¶
Snippet Macros¶
The following macros are used inside Javatar snippet files (*.javatar) which will be parsed by Javatar and Sublime Text.
- %package_path% = Package path
- %class% = Class name
- %file% = File path
- %file_name% = File name (equivalent to %class%.java)
- %package% = Package code (for example package java.utils; or same as package %packages_path%;)
- All Sublime Text‘s snippet macros can be used within Javatar snippets. For example: ${1} or ${2://Comment}
Javatar Packages¶
Javatar required packages file (*.javatar-packages) to correctly import necessary Java’s packages. These files contain all classes, fields, methods and packages to use with Javatar.
Javatar Packages file is a JSON file. You can read more details about each key and value in Proto.javatar-packages located within Javatar‘s Java folder (can be accessed via Preferences > Package Settings > Proto.javatar-packages or via command palette by type Javatar Proto).
However, their are 2 special keys that are not normally used within Javatar Packages which are...
- experiment
- Set this to true to exclude this package from Javatar‘s packages list.
- always_import
- Set this to true to always import this package even no class is used (this will import as package.*).
Both keys are boolean type and also optional to use.
Additional Packages¶
By default, Javatar is not include any additional packages inside its package. This helps Javatar faster to install/update from Package Control but that not provides any support for some features (for example, Organize Imports). To solve this problem, Javatar will automatically download and install necessary packages when startup.
For other packages, you can download and install using Packages Manager... > Install Packages... menu.
Javatar Grammar¶
Javatar grammar (*.javatar-grammar) is used to assigned a name to Java elements such as keywords, strings or similar just like TextMate’s grammar. This allow Javatar to get informations about document more accurate.
Javatar have it own parser that will parse your document using this grammar. Since Javatar is using GrammarParser, it’s grammars are also a GrammarParser‘s grammar.
More informations about how grammar works is on GrammarParser readme.
Package Channels¶
Stable Channel¶
Stable channel is a default channel for every user who installed Javatar. This channel will release only fully working features and hide all incomplete features.
Development Channel¶
Development channel is a optional channel for user who want to try upcoming features which may not fully working or need improvements. All upcoming features will appear in Development Section only.
Note
Stable channel update notes also apply on development channel as well.
Package Updates Notifications¶
In order to notice important notes to all users, in stable channel or development channel or both, Javatar use custom notification system which will notice you only once when Javatar is ready to use. You can opt out this notification by settings message_id to -1 in Javatar‘s user settings file, note that you can see update notes in README file or you will miss further important update notes.
Statistics and Usages Policy¶
From 13 Apr 2014, Javatar will collect statistics and usages of Javatar to help improve the package features. Data we have collected are your Javatar‘s settings and Sublime Text informations. To disable automatic sending statistics and usages, set send_stats_and_usages to false and Javatar will not send any statistics and usages anymore. However, additional packages statistics still collected for packages improvements and selections.
Actions History¶
Actions History tracks how you use Javatar and helps solve the problem. By provides useful informations as request by developer (only when you submit an issue). A Javatar Action History Report will looks similar to this when using it properly...
## Javatar Report
### System Informations
* Javatar Version: `14.04.15.00.29b`
* Sublime Version: `3059`
* Package Path: `/Users/USER_NAME/Library/Application Support/Sublime Text 3/Packages`
* Javatar Channel: `stable`
* Sublime Channel: `stable`
* Is Debug Mode: `False`
* Platform: `osx`
* As Packages: `True`
* Package Control: `True`
* Architecture: `x64`
* Javatar's Parent Folder: `Javatar`
* Is Project: `True`
* Is File: `True`
* Is Java: `True`
### Action List
1. Startup
2. Reset all settings
3. Reset all snippets
4. Reset all default packages
5. Read settings
6. Load snippets
7. Check news
8. Ready
9. Javatar snippet AbstractClass.javatar loaded
10. Analyse snippet [file=Packages/Javatar/snippets/AbstractClass.javatar]
11. Javatar snippet Class.javatar loaded
12. Analyse snippet [file=Packages/Javatar/snippets/Class.javatar]
13. Javatar snippet Enumerator.javatar loaded
14. Analyse snippet [file=Packages/Javatar/snippets/Enumerator.javatar]
15. Javatar snippet Interface.javatar loaded
16. Analyse snippet [file=Packages/Javatar/snippets/Interface.javatar]
17. Load Java default packages
18. Javatar default package Proto.javatar-packages loaded
19. Analyse package [file=Packages/Javatar/Java/Proto.javatar-packages]
20. Javatar default package JavaSE8.javatar-packages loaded
21. Analyse package [file=Packages/User/JavaSE8.javatar-packages]
22. Check packages update
Javatar do not automatically send these informations. You have to reply an issue with these informations yourself.
Actions History can be disabled by settings enable_actions_history to false.
[1] | Referred from Javapocalypse video |