Creating a New Plugin Project (without checking out the source)
Because we use Maven, it is possible to develop a plugin without even checking out the source code. This is because we deploy our compiled artifacts to Maven Central, and because we have developed a plugin archetype. If you are not familiar with Maven archetypes, you can think of them as a project template that gets you started quickly with a project that compiles and has tests. Our plugin template will even allow you to launch SQuirreL within the plugin project that you have created for testing. You do not need to download anything if you have Maven installed and configured properly (see setup guide). Maven will download everything that it needs to compile, test and launch your plugin.
In this example, we will create a new plugin called the "AwesomePlugin" because, it's simply awesome! In general, you should think of a name that adequately describes the functionality of your plugin (send an e-mail to the developers list - squirrel-sql-develop at lists.sourceforge.net - if you are unsure). To create this new plugin project from the command-line, you can execute the following command:
mvn archetype:generate -DarchetypeGroupId=net.sf.squirrel-sql.plugins -DarchetypeArtifactId=squirrelsql-plugin-archetype -DarchetypeVersion=3.3.0-rc3
After executing that command you will see Maven downloading artifacts that it needs to create the project and eventually, you will see the following prompt:
[INFO] Archetype repository missing. Using the one from [net.sf.squirrel-sql.plugins:squirrelsql-plugin-archetype:3.3.0-rc1] found in catalog remote Define value for property 'groupId': :
For "groupId", you should choose "net.sf.squirrel-sql.plugins" since this is the groupId that all other SQuirreL plugins use in Maven Central (You want people to be able to find your awesome plugin, right?). Next, you will be prompted for "artifactId":
Define value for property 'artifactId': :
This should be a string that is all lower case, having no spaces or underscores, ideally no special characters or dashes and doesn't have the word "plugin" in it. It also must not use an "artifactId" that is already used (again, its probably to send an e-mail to the developers list - squirrel-sql-develop at lists.sourceforge.net - to introduce your new plugin and "artifactId".) For this example, our "artifactId" will simply be "awesome". The next prompt will ask you for the "version" to start with:
Define value for property 'version': 1.0-SNAPSHOT: :
The default value of "1.0-SNAPSHOT" is fine. Don't worry about the "-SNAPSHOT" business, it is desirable when you are developing, and when your plugin is released the version will be sensible (more on releasing your plugin later). Alright, the next prompt is for "package";
Define value for property 'package': net.sf.squirrel-sql.plugins: :
Unfortunately, the default package contains a "-" which is good for Maven groupIds, but bad for Java packages. Most other plugins are located in the package "net.sourceforge.squirrel_sql.plugins.<pluginName>". You can choose whatever package you want, but in our case we will use the package "net.sourceforge.squirrel_sql.plugins.awesome" and press <enter>. The next prompt is for "pluginName":
Define value for property 'pluginName': :
Here, you should choose a meaningful name that is related to the artifactId, if not the same. Again it should not include the word "plugin", but it should begin with a capital letter, followed by lowercase letters. If it is more then one word, it should be camel-case, like the name of a Java class. The reason for this is that it will become the class name of your plugin. The archetype will give it a "Plugin" prefix. So, in our case, we will use "Awesome" as the value for the plugin name. The main plugin class that is generated will then be AwesomePlugin.java. Next, just hit <enter> to accept the values you have chosen, and the project will be created beneath a directory with the same name as the value for artifactId. When you cd into the "awesome" directory, and run the "tree" command, you will see the following structure:
manningr@dell-devpc:~/workspace-maven/tmp/awesome$ tree . |-- pom.xml `-- src |-- main | |-- java | | `-- net | | `-- sourceforge | | `-- squirrel_sql | | `-- plugins | | |-- AwesomePlugin.java | | |-- ExampleExceptionFormatter.java | | |-- ExampleSqlExecutionListener.java | | |-- ScriptDB2ProcedureAction.java | | `-- ScriptDB2ViewAction.java | `-- resources | |-- doc | | |-- changes.txt | | |-- licence.txt | | `-- readme.txt | `-- net | `-- sourceforge | `-- squirrel_sql | `-- plugins | `-- awesome | `-- awesome.properties `-- test `-- java `-- net `-- sourceforge `-- squirrel_sql `-- plugins |-- AwesomePluginTest.java |-- ExampleExceptionFormatterTest.java `-- ExampleSqlExecutionListenerTest.java 20 directories, 13 files
At this point, you can do "mvn clean install" and the source is compiled and tests are run. You may also issue the following command to launch SQuirreL with your plugin loaded and ready to use:
mvn clean install -P launch
If you use a Java IDE, you can now "import" the project into your IDE by giving it the directory where the genereated pom.xml file resides.
The files that are created by the archetype are heavily commented to introduce you to SQuirreL plugin concepts and to give you ideas. However, if what you read is unclear, please provide this feedback to the developers list (squirrel-sql-develop at lists.sourceforge.net).