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 providing many features that help develop Java applications faster and easier.
- Packages and Subpackages creation
- Class (also Abstract), Interface and Enumeration snippets with package/class name auto-complete and auto-import
- Project/Package/Class build and run with dependencies [2]
- Packages path in status bar
- External libraries packages
- Internal console with input supports
- Organize Imports [2]
For full feature list, please see Release Changelog
[2] | (1, 2) Organize Imports will not support classes inside dependencies except provided by Javatar Packages |
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 a folder which can be accessed via the Preferences > Browse Packages...
Release Changelog¶
First release (20 December 2014)¶
- Create packages
- Create classes, enumerators, interfaces
- Class corrections
- Build System
- Action History
- Organize imports
- Javatar packages
- Javatar stats and usages
- Project Settings
- Javatar shells and run class feature
- Compilation errors and StackTrace code highlighting (syntax files)
- Parallel build threads
- Dependency settings
- Installed JDKs settings and automatic detection
- Project data restoration
- Build notifications via SubNotify
- Program argument settings
- Build and Run outputs’ target group settings
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 workflow.
This should take some time since I am going to explain everything you might need to know. But in a normal work, you would do all of this in a few minutes.
At the end of this chapter, we will see a simple application that takes our input and responds 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 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 contain 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 an input box.
Note
Key
is Control
on Windows, 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 is ending up in a wrong place because we did not set the source folder yet.
What is a source folder? Source folder is, obviously, a folder which contains source code files.
Since, we want our source code to be placed in 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
If project data restoration feature is disabled and you did not save your project, Source Folder and Dependencies settings might be reset when you restarted Sublime Text.
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 lets 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 created inside a proper package path. Isn’t that great?
So, Create Package command is useless? Well, not so much. Sometimes, you might need to creates a package before create a class to organize packages, and later you will fill it up with a bunch of classes. And that is the time when Create Package comes in.
Package Path¶
Right now, if you look at a status bar at the bottom of the window, you will notice that there is a package path showing. This will change when you switch to another tab that is Java file, indicated which package current file is in.
Coding Time!¶
It is a fun time! Let’s code a simple application that takes 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 have 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
- Class
- Enumerator
- Interface
- And your own Javatar‘s snippets
- Operations...
- Organize Imports
- Correct Class
- Project Settings...
Set Program Arguments
Set Source Folder
- Dependencies...
- Add External .jar
- Add Class 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]
- 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 sections.
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 or correct class
- More details on Operations
Project Settings¶
- Adjust settings for current projects
- More details on Projects Settings
Javatar Settings¶
- Adjust settings for global projects (all projects)
- Most settings are the same as project 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 used to insert class or package information 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¶
Relative Creations¶
In all create related commands, all packages and classes will be created relative to the 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" |
Classes with main method¶
To create a class with main method, just add AsMain
at the end of your class name.
Javatar will automatically add main method when the class is created.
Customized Classes¶
You can create a class with custom visibility (default class visibility is public
) by adding one of the keyword public
, private
, protected
and default
before your class name. If you want to create an abstract or final class just add abstract
or final
after the visibility.
- Examples:
privateBattleShip
- Class “BattleShip” is created with “private” visiblity
protectedAbstractBattleShip
- Class “BattleShip” is created with “protected” visibility and “abstract” modifier
wargame.entity.defaultBattleShip
- Class “BattleShip” is created with “default” visibility in “wargame.entity” package
Note
The keyword is order-sensitive but not case-sensitive.
Inheritances Helper¶
You can create a class included with inheritances of classes and interfaces by using special characters.
To extends a class, add :
(colon) followed by a class name (or a list of class names separated by commas if it is a enumerator).
To implements an interface, add <
(left angle bracket) followed by a list of interface names separated by commas.
If you are on Development Channel, Javatar will also automatically organize imports when class is created.
- Examples:
BattleShip:BattleUnit
- Class “BattleShip” is inherited from “BattleUnit” class (has “extends” in the code)
BattleShip:BattleUnit<WaterUnit
- Class “BattleShip” is both inherited from “BattleUnit” class and “WaterUnit” interface
BattleShip<Carrier,WaterUnit:BattleUnit
- Class “BattleUnit” is inherited from “BattleUnit” class, “Carrier” interface and “WaterUnit” interface
wargame.entity.defaultAbstractBattleShip:BattleUnit<Carrier,WaterUnit
- Abstract class “BattleUnit” is created in “wargame.entity” package with “default” visibility and is inherited from “BattleUnit”, “Carrier” and “WaterUnit” class/interface
Inheritances is case-sensitive but not order-sensitive.
Note
Despite, Javatar allows you to create “private” or “protected” classes. It does not make sense to create a private or protected class since another class can not see a new class you created.
Operations¶
Operations help you do a 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 the file name and location of the current file and correct it on first class definition.
Organize Imports¶
Javatar will automatically import all necessary packages and remove unused packages for you. This is done within 7 sub-steps.
- Javatar gathering imports informations from current file
- Javatar lets you select a package that has the same class
- Javatar imports “default imports” and Java’s packages
- Javatar asks you to enter the package name for missing classes
- Javatar asks for package name that you want to enter manually
- Javatar clear all imports in the current file
- Javatar imports all packages that have been processed within step 1-4
Projects Settings¶
The 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
Set Program Arguments¶
By default, Javatar will not pass parameters when running an application through the Run Main Class command (see Getting Started for an example). Set Program Arguments allows you to specify what arguments should be passed on main execution.
Dependencies¶
Javatar supports 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 specify a default package (mostly) based-on current working folder or folder contains current working files (more details in next section). Many projects might use multiple folders and some of them are not source folder. Set source folder helps solve this issue by letting 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.
Settings¶
Settings can be accessed via the Preferences > Package Settings > Javatar from the menu bar or via command palette by type Preference Javatar
.
Default settings should not be modified. However, you can copy the relevant settings in Javatar‘s user settings file.
Some settings contain parameters for special value such as Source Folder or Project Directory. The followings are all parameter 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 quoted all path specific value to escape the spaces.
Default Package Detection¶
Javatar will specify the default package with these steps...
- Source Folder specified in the current project file (when open project)
- Project folder in current project file (when open project or folder)
- Folder contains the current file (when open file)
- Specify current package as
(Unknown Package)
Javatar will refuse to create packages or classes within an 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 on your computer and select the best one.
Here are the steps it takes to select the best JDK for most projects...
- Run a checking command to see that Java has been setup as default
- Search all JDK directories 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.
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.
- Browse Commands... :
- Help and Support... :
Key+Shift+H
- This will open quick panel, showing you all utilities that help solve the issue (most requested to do by developer).
- Help and Support... :
- Builds... :
Key+Shift+B
- This will open quick panel to select which build you want to perform.
- Builds... :
- Calls... :
Key+Shift+J
- This will open quick panel to select which information you want to insert.
- Calls... :
- Operations... :
Key+Shift+O
- This will open quick panel to select which operation you want to perform.
- Operations... :
- Create new... :
Key+Shift+N
- This will open quick panel, showing you all possible types to create.
- Create new... :
- Create new package :
Key+Shift+P
- This will open input panel, just like when you create a new package.
- Create new package :
- Organize Imports :
Key+Shift+I
- This will organize imports on current file.
- Organize Imports :
- Project Settings :
Key+Shift+,
- This will open quick panel, showing you all settings you can adjust for current project.
- Project Settings :
- Javatar Settings :
Key+Shift+.
- This will open quick panel, showing you all settings you can adjust for global projects.
- Javatar Settings :
Note
Key
is Control
on Windows, Linux and Command
on OS X.
Build System¶
Javatar‘s build system using its internal shell to build your classes. Javatar builds parameters are based on default Sublime Text‘s JavaC build settings. You can change the build command via a 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
Javatar 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 parameters, 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 Parameters¶
The following parameters 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 aspackage %packages_path%;
) - All Sublime Text‘s snippet parameters 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.
- Set this to
always_import
- Set this to
true
to always import this package even no class is used (this will import aspackage.*
).
- Set this to
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.
If you want to suggest or add Javatar Packages to the package repository. Please leave an issue in Javatar Packages repository.
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, its 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.
Note
From Javatar 1.0.0 and later, Package Channels has no effect on features except for Development Section. There will be no package channel on newer version of Javatar.
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: `1.0.0`
* 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
.
Notifications¶
Javatar will show a notification when the build is finished or failed via SubNotify plugin.
You can install SubNotify by follow these instructions on this page.
Year Book¶
A lookback of Javatar over years...
20 December 2014...¶
Javatar has reach its first release!
Stats: 10.0k installs
Take a look of full feature list here Release Changelog
15 June 2014...¶
Stats: 5.5k installs
It’s been a year since Javatar was released. There’re so many things that Javatar has been added and improved over the year. Started from a simple plugin that helps create a package and class easier, and becomes a more capable plugin to build and run Java projects. 1 year, many things changed, yet there’re more to come...
15 June 2013...¶
Javatar‘s first commit.
License¶
::Javatar::
The MIT License (MIT)
Copyright (c) 2014 Sirisak Lueangsaksri
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
[1] | Originally from Javapocalypse video |