All Projects → forge → Core

forge / Core

Licence: epl-1.0
Forge Core Framework APIs and Implementation

Programming Languages

java
68154 projects - #9 most used programming language

Projects that are alternatives of or similar to Core

Line-Clipper
💻Efficient navigation between browser and IDE while working on GitHub.
Stars: ✭ 64 (-67.18%)
Mutual labels:  productivity, ide
Awesome Startup Tools List
List of all tools (apps, services) that startups should use.
Stars: ✭ 188 (-3.59%)
Mutual labels:  productivity
Awesome Pycharm
A curated list of resources for learning and using PyCharm, a Python IDE from JetBrains
Stars: ✭ 174 (-10.77%)
Mutual labels:  ide
Go Wasm
The in-browser IDE for Go
Stars: ✭ 186 (-4.62%)
Mutual labels:  ide
Kaitai struct webide
Online editor / visualizer for Kaitai Struct .ksy files
Stars: ✭ 175 (-10.26%)
Mutual labels:  ide
Intellij Haxe
Haxe plugin for IntelliJ Platform based IDEs (IDEA, Android-Studio)
Stars: ✭ 188 (-3.59%)
Mutual labels:  ide
Alfred Aws Console Services Workflow
A powerful workflow for quickly opening up AWS Console Services in your browser or searching for entities within them.
Stars: ✭ 171 (-12.31%)
Mutual labels:  productivity
Aaru
Aaru Data Preservation Suite
Stars: ✭ 193 (-1.03%)
Mutual labels:  ide
Sudo Productivity
Boost your "productivity" to the max! A fun project made for slackers by slackers.
Stars: ✭ 190 (-2.56%)
Mutual labels:  productivity
Pomidor
Pomidor is a simple and cool pomodoro technique timer.
Stars: ✭ 183 (-6.15%)
Mutual labels:  productivity
Spectnetide
ZX Spectrum IDE with Visual Studio 2017 and 2019 integration
Stars: ✭ 182 (-6.67%)
Mutual labels:  ide
Njt
njt (npm jump to): a quick navigation tool for npm packages
Stars: ✭ 179 (-8.21%)
Mutual labels:  productivity
Roboware Studio
An IDE environment for ROS development.
Stars: ✭ 189 (-3.08%)
Mutual labels:  ide
Blender Launcher
Standalone client for managing official builds of Blender 3D
Stars: ✭ 174 (-10.77%)
Mutual labels:  productivity
Pyzo
Python to the people
Stars: ✭ 192 (-1.54%)
Mutual labels:  ide
Fake
嵌入式脚本语言 Lightweight embedded scripting language
Stars: ✭ 172 (-11.79%)
Mutual labels:  ide
Fast Ide
🕺Fast Integrated Development Environment 😻
Stars: ✭ 181 (-7.18%)
Mutual labels:  ide
Zerobranestudio
Lightweight Lua-based IDE for Lua with code completion, syntax highlighting, live coding, remote debugger, and code analyzer; supports Lua 5.1, 5.2, 5.3, 5.4, LuaJIT and other Lua interpreters on Windows, macOS, and Linux
Stars: ✭ 2,255 (+1056.41%)
Mutual labels:  ide
Tubekit
🧪 kubectl alternative with quick context switching, kubectl on steroids
Stars: ✭ 194 (-0.51%)
Mutual labels:  productivity
Bridge.
Minecraft Add-on Editor | We strive to provide the best development experience possible
Stars: ✭ 193 (-1.03%)
Mutual labels:  ide

image::http://design.jboss.org/jbossforge/logo/final/jbossforge_logo_600px.png[]

The fastest way to build applications, share your software, and enjoy doing it.

image:https://github.com/forge/core/workflows/GitHub%20CI/badge.svg["Actions Status", link="https://github.com/forge/core/actions"] image:https://img.shields.io/github/license/forge/core.svg["License", link="https://www.eclipse.org/legal/epl-v10.html"] image:https://maven-badges.herokuapp.com/maven-central/org.jboss.forge/forge-distribution/badge.svg["Maven Central", link="https://maven-badges.herokuapp.com/maven-central/org.jboss.forge/forge-distribution"] image:https://kiwiirc.com/buttons/irc.freenode.net/forge.png["Visit our IRC channel", link="https://kiwiirc.com/client/irc.freenode.net/#forge"]

What's new and noteworthy?

  • JDK 8: Forge 3 now runs on JDK 8 as its minimum requirement. Hello lambdas!

  • Unix-like option names: The shell option names are now more unix-like: Eg: --targetPackage is now --target-package.

== Download Forge 3: JBoss Forge is packaged inside your favorite IDE plugin and also as a standalone ZIP file. They are independent of each other.

=== Get Started with the Command line tools:

Getting started with the command line tools is easy:


forge

Forge is now ready to go.

==== Install addons (not needed if using the offline zip)

Install the required addons by running the following commands:

[source,cmd]

forge --install groupId:artifactId,version

  • Forge will install the required dependencies for each addon.

IMPORTANT: Make sure your settings.xml is properly configured to use the Maven central repository or, if you wish to use a SNAPSHOT version from a core addon, the JBoss Nexus Repository, otherwise the installation will fail. Instructions on how to setup your settings.xml can be found on https://community.jboss.org/wiki/MavenGettingStarted-Developers

If you wish to install the core addons including the shell, "Project: New", the "Java EE" commands, and all other provided functionality, you should run the following command:

[source,cmd]

forge --install core

If you only wish to install the Forge 2 Shell based on link:http://aeshell.github.io/[Aesh], run the following command instead:

[source,cmd]

forge --install shell

If you wish to remove any addon, you can use the following command:

[source,cmd]

forge --remove groupId:artifactId,version

== Get Started with the Eclipse Plugin:


Forge 3 is known to work with Eclipse Mars (Eclipse 4.5) or higher versions. Older versions of Eclipse are not supported.


This plugin starts the Forge Container and your installed addons, so you can use them directly in your workspace

  • Press Ctrl + 4 to show the installed addons that you may interact with (these addons use the UI addon, hence providing a user interface - see Developing an UI Addon for more details).

== Available addons

[options="header"] |=== |Addon name |Included in Eclipse Plugin ?

|link:addon-manager/README.asciidoc[Addon Manager] |yes

|link:addons/README.asciidoc[Addons] |yes

|link:configuration/README.asciidoc[Configuration] |yes

|link:convert/README.asciidoc[Convert] |yes

|link:dependencies/README.asciidoc[Dependencies] |yes

|link:dev-tools-java/README.asciidoc[Dev Tools - Java] |yes

|link:environment/README.asciidoc[Environment] |yes

|link:facets/README.asciidoc[Facets] |yes

|link:git/README.asciidoc[Git] |yes

|link:javaee/README.asciidoc[Java EE] |yes

|link:maven/README.asciidoc[Maven] |yes

|link:parser-java/README.asciidoc[Parser Java] |yes

|link:parser-json/README.asciidoc[Parser Json] |yes

|link:parser-xml/README.asciidoc[Parser XML] |yes

|link:projects/README.asciidoc[Projects] |yes

|link:resources/README.asciidoc[Resources] |yes

|link:scaffold/README.asciidoc[Scaffold] |yes

|link:shell/README.asciidoc[Shell] |yes

|link:templates/README.asciidoc[Templates] |yes

|link:text/README.asciidoc[Text] |yes

|link:ui/README.asciidoc[User Interface (UI)] |yes

|===

== Developing an Addon

Forge addons are simple Maven projects with a special classifier "forge-addon". This classifier is used while installing an addon so the Furnace container can calculate its dependencies, freeing you from http://robjsoftware.org/2007/07/13/classloader-hell/[Classloader hell].

One of the most important things to know about developing a Forge addon, is that the Furnace runtime container (the core of Forge), is actually an embeddable, modular Java container. This means that each addon has its own ClassLoader and that addons share classes from each other, in addition to supplying their own local classes. Furnace builds a graph of addon dependencies at runtime, and automatically calculates which addons should see classes from other addons.

For now, however, just treat your first addon as if it were any other Java project. The differences between a "modular" and "traditional" environment are not as great as you might think, and the Furnace development model has been created in a way that should make these differences seem natural, almost transparent.

=== Create a Maven project

Forge Addons must be JARs published with a 'forge-addon' classifier. Add this plugin configuration to your pom.xml:

[source,xml]

org.apache.maven.plugins maven-jar-plugin create-forge-addon package jar false forge-addon ----

In order to use CDI and services from other addons in your addon, you'll need to reference the Furnace CDI container addon as a dependency your pom.xml file:

[source,xml]

org.jboss.forge.furnace.container cdi forge-addon provided ----

CAUTION: Addon dependencies MUST be declared in the Maven pom.xml that produces your forge-addon classified artifact; otherwise, Furnace will NOT use this dependency as a forge-addon. Instead, addon dependencies declared via transitive dependencies will be included as local JAR files and re-bundled with your addon. More than likely, re-bundling a forge-addon in your Addon is NOT what you want.

Your complete POM should now look something like this:

[source,xml]

4.0.0

com.example example 1.0.0-SNAPSHOT

My First Addon

3.5.1.Final org.jboss.forge forge-bom ${version.forge} pom import org.jboss.forge.furnace.container cdi forge-addon provided org.apache.maven.plugins maven-jar-plugin create-forge-addon package jar false forge-addon ----

=== Add behavior to your addon

A service is implemented as a POJO (Plain Old Java Object):

[source,java]

public class ExampleServiceImpl { public String doSomething() { // Do stuff... } }

However, best practices favor creating a service interface, otherwise consumers will be required to request your specific service implementation. For example:

[source,java]

public interface ExampleService { public String doSomething(); }

Then simply implement the service interface:

[source,java]

public class ExampleServiceImpl implements ExampleService { public String doSomething() { // Do stuff... } }

=== Re-use functionality from other addons:

Forge has a modular architecture that enables you to re-use functionality from other addons, directly in your own addon code. In order to achieve this, you must add addon-dependencies in your pom.xml file.

[source,xml]

... org.jboss.forge.addon resources forge-addon provided org.jboss.forge.addon ui forge-addon provided
  <!-- Furnace Container -->
  <dependency>
     <groupId>org.jboss.forge.furnace.container</groupId>
     <artifactId>cdi</artifactId>
     <classifier>forge-addon</classifier>
     <scope>provided</scope>
  </dependency>

...

==== What scope should my addon dependencies be?

There is a simple rule that will make this an easy decision:


"compile if everyone knows, provided if I know, runtime if nobody knows."


To explain, if you never publicly expose types (classes, interfaces, etc...) from another addon in the outward-facing APIs of your addon, then you should include that addon as provided scope. If you do, however, expose classes from that addon in the public APIs of your code, then that addon should be labeled as compile scope (default,) which means that this dependency will be 'exported' to consumers that depend on your addon.

Addon dependencies may also be made optional if consumers of your addon should be able to choose whether or not certain functionality is enabled, or if your addon behaves differently when other addons are already deployed to the container.

The following chart explains this in detail. Assume that our addon depends on the resources addon, which provides the ResourceFactory and FileResource classes:

[cols="1a,2,3", options="header"] |=== |Example |Scope should be |Explanation

| The Resource<?> and ResourceFactory types are provided by the resources addon. Your addon defines InternalExample. [source,java]

public class InternalExample { @Inject private ResourceFactory factory;

public void doSomething(File file) { Resource<?> r = factory.create(file); System.out.println("New resource: " + r)a } }

|provided |Consumers of your addon never see classes or interfaces from the resources addon; it is only used internally as an implementation detail and is not exposed in your public API.

Your addon should depend on the resources addon at provided scope.

| The Resource<?> and ResourceFactory types are provided by the resources addon. Your addon defines ExposedExample. [source,java]

public class ExposedExample { @Inject private ResourceFactory factory;

public Resource> doSomething(File file) { Resource> r = factory.create(file); return r; } }

|compile |Consumers of your addon require classes from the resources addon to interact with your code, since it has been referenced in the your addon's public API.

Your addon should depend on the resources addon at compile scope.

| The type LockCreator is defined by addon X. [source,java]

public class LockCreator { public void createFile( @Observes PostStartup event) { File lock = new File("lockfile"); lock.createNewFile(); } }

Your addon defines LockConsumer, which requires that a file "lockfile" be available when it runs. This file is created by addon X. [source,java]

public class LockConsumer { public void deleteLock() { File lock = new File("lockfile"); Assert.assertTrue(lock.exists()); } }

|runtime |Your addon makes assumptions about the runtime environment that are satisfied by the presence of addon X, but your addon does not depend on or expose types from addon X in its APIs.

Your addon should include addon X at runtime scope.

| The type Logger is defined by addon X, but addon X does not include an implementation of its own logging interface. [source,java]

public interface Logger { public void log(String message) }

Your addon defines LoggerConsumer, which depends on addon X in order to use Logger, but requires that another addon (addon Y) actually provide an logging implementation. [source,java]

public class LoggerConsumer { @Inject private Imported loggers;

public void logEverything() { for( Logger log : loggers { log.log("Log for you!"); } } }

|provided / runtime |Your addon requires instances of Logger, which is defined in addon X, but provided by addon Y (for instance), thus your addon requires addon Y to provide an instance of Logger, but does not need to import or compile against addon Y's types directly (they are provided by Furnace). Your addon does not expose the Logger type from addon X in its APIs.

Your addon should include addon X at provided scope, and addon Y at runtime scope. |===

=== Test your addon

One of the most important concepts of writing a Forge addon is writing tests using the Furnace test harness. This allows you to test your code in an actual Furnace environment, and verify that things are behaving as expected. Typically we suggest using a separate project to test your addon in order to keep concerns separate, which tends to lead to cleaner code and fewer surprises.

For simplicity's sake, we'll assume that your addon uses the default Furnace container (org.jboss.forge.furnace.container:cdi).

==== Set up the test-harness in your build descriptor (pom.xml)

Add the following dependencies to your pom.xml file if they are not already there. Make sure that the Furnace versions are the same as the rest of your project.

[source,xml]

org.jboss.forge.furnace.test furnace-test-harness FURNACE_VERSION test org.jboss.forge.furnace.test arquillian-furnace-classpath FURNACE_VERSION test ----

If you are writing tests in a separate project or sub-project, you should also add a dependency to your addon, or to the addon you wish to test (you can test anything you like.)

[source,xml]

com.example example forge-addon YOUR_VERSION test ----

==== Write your first test

Now, you'll need to create a test class with the following layout, using the standard JUnit test APIs:

[source,java]

package org.example;

import org.jboss.arquillian.container.test.api.Deployment; import org.jboss.arquillian.junit.Arquillian; import org.jboss.forge.arquillian.archive.AddonArchive; import org.jboss.shrinkwrap.api.ShrinkWrap; import org.junit.Assert; import org.junit.Test; import org.junit.runner.RunWith;

@RunWith(Arquillian.class) public class ExampleFurnaceTest {

@Deployment public static AddonArchive getDeployment() { AddonArchive archive = ShrinkWrap.create(AddonArchive.class); return archive; }

@Test public void testSomething() throws Exception { Assert.fail("Not implemented"); } }

Then you'll need to add some configuration so that your addon will be deployed to the test environment. This is done using the @AddonDeployment annotation. You'll also need to add an addon dependency link from your test case to your addon (otherwise the test case will not be able to use any of your addon's classes or services.)

[source,java]

@RunWith(Arquillian.class) public class ExampleFurnaceTest {

@Deployment @AddonDeployments({ @AddonDeployment(name = "org.example:example", version = "YOUR_VERSION") }) public static AddonArchive getDeployment() { AddonArchive archive = ShrinkWrap.create(AddonArchive.class) .addBeansXML() .addAsAddonDependencies( AddonDependencyEntry.create("org.example:example", "YOUR_VERSION"), ); return archive; }

@Test public void testSomething() throws Exception { Assert.fail("Not implemented"); } }

NOTE: The @AddonDeployment annotation is used to specify addons that must be deployed before the Addon-Under-Test is deployed in Furnace. The AddonDependencyEntry.create(...) method is used to specify addons that the Addon-Under-Test depends on. You can use the @AddonDependency annotation if you want to deploy AND make your Addon-Under-Test dependent on the specified addon. By using the @AddonDependency annotation you no longer need to specify AddonDependencyEntry.create(...) in your AddonArchive.

Now that the test case deploys and depends on your addon, you may access services from it via injection:

[source,java]

@RunWith(Arquillian.class) public class ExampleFurnaceTest {

@Deployment @AddonDeployments({ @AddonDeployment(name = "org.example:example", version = "YOUR_VERSION") }) public static AddonArchive getDeployment() { AddonArchive archive = ShrinkWrap.create(AddonArchive.class) .addBeansXML() .addAsAddonDependencies( AddonDependencyEntry.create("org.example:example", "YOUR_VERSION"), ); return archive; }

@Inject private ExampleService service;

@Test public void testSomething() throws Exception { Assert.assertNotNull(service); Assert.assertNotNull(service.doSomething()); } }

This is the basic premise of using the test-harness. For detailed examples, take a https://github.com/forge/core/tree/master/resources/tests/src/test/java/org/jboss/forge/addon/resource[look at some of the existing Forge test cases] in our github repository.

NOTE: The version parameter in @AddonDependency and in the AddonDependencyEntry.create(...) method are optional. By not specifying them means that the test harness will attempt to find the version based on the tests' build descriptor (pom.xml). In this case, if the dependent addon is not present in the tests' build descriptor, the test execution should fail.

=== Install your addon in the local maven repository:

Depending on the Forge environment in which you are running, installation steps will differ.

For Eclipse:: Open the Forge quick-assist menu, select either "Build and install an Addon" or "Install an addon" to build and install your project, or install a pre-built maven artifact.

For the Shell::

[source,cmd]

mvn clean install

Run

[source,cmd]

./forge --install yourgroupId:artifactId,version

WARNING: This coordinate is NOT the same as Maven's. You MUST use a comma (,) between the artifactId and the version.

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].