Author: jleroux
Date: Fri Sep 23 20:10:23 2016
New Revision: 1762086
URL: http://svn.apache.org/viewvc?rev=1762086&view=rev
Log:
Updates: the README.md.html file for the From Ant to Gradle Wiki page
Modified:
ofbiz/trunk/tools/documentation/README.md.html
Modified: ofbiz/trunk/tools/documentation/README.md.html
URL:
http://svn.apache.org/viewvc/ofbiz/trunk/tools/documentation/README.md.html?rev=1762086&r1=1762085&r2=1762086&view=diff
==============================================================================
--- ofbiz/trunk/tools/documentation/README.md.html (original)
+++ ofbiz/trunk/tools/documentation/README.md.html Fri Sep 23 20:10:23 2016
@@ -19,6 +19,12 @@
<blockquote>
<p><em>Note</em>: if you are using Eclipse, make sure of running the
appropriate Eclipse command <code>gradlew eclipse</code> before creating the
project in Eclipse. This command will prepare OFBiz for Eclipse with the
correct classpath and settings by creating the.classpath and .project files.</p>
</blockquote>
+<h2 id="security">Security</h2>
+<p>You can trust the OFBiz Project Management Committee members and committers
do their best to keep OFBiz secure from external exploits, and fix
vulnerabilities as soon as they are known. Despite these efforts, if ever you
find and want to report a security issue, please report at: security @
ofbiz.apache.org, before disclosing them in a public forum.</p>
+<blockquote>
+<p><em>Note</em>: Be sure to read this Wiki page if ever you plan to use RMI,
JNDI, JMX or Spring and maybe other Java classes OFBiz does not use Out Of The
Box (OOTB): <a
href="https://cwiki.apache.org/confluence/display/OFBIZ/The+infamous+Java+serialization+vulnerability";>The
infamous Java serialization vulnerability</a></p>
+</blockquote>
+<p>You can find more information about security in OFBiz at <a
href="https://cwiki.apache.org/confluence/display/OFBIZ/Keeping+OFBiz+secure";>Keeping
OFBiz secure</a></p>
<h2 id="quick-start">Quick start</h2>
<p>To quickly install and fire-up OFBiz, please follow the below instructions
from the command line at the OFBiz top level directory (folder)</p>
<h3 id="prepare-ofbiz">Prepare OFBiz:</h3>
@@ -153,7 +159,7 @@
<p>Create a new tenant in your environment, create the delegator, load initial
data with admin-user and password (needs multitenant=Y in general.properties).
The following project parameters are passed:</p>
<ul>
<li>tenantId: mandatory</li>
-<li>tenantName: mandatory, name of the tenant</li>
+<li>tenantName: optional, default is value of tenantId</li>
<li>domainName: optional, default is org.apache.ofbiz</li>
<li>tenantReaders: optional, default value is seed,seed-initial,demo</li>
<li>dbPlatform: optional, D(Derby), M(MySQL), O(Oracle), P(PostgreSQL)
(default D)</li>
@@ -161,7 +167,7 @@
<li>dbUser: optional, username of the database</li>
<li>dbPassword: optional, password of the database</li>
</ul>
-<p><code>gradlew createTenant -PtenantId=mytenant -PtenantName="My
Name"</code></p>
+<p><code>gradlew createTenant -PtenantId=mytenant</code></p>
<p><code>gradlew createTenant -PtenantId=mytenant -PtenantName="My
Name" -PdomainName=com.example -PtenantReaders=seed,seed-initial,ext
-PdbPlatform=M -PdbIp=127.0.0.1 -PdbUser=mydbuser
-PdbPassword=mydbpass</code></p>
<p>If run successfully, the system creates a new tenant having:</p>
<ul>
@@ -193,7 +199,6 @@
<p>listens on port <strong>5005</strong></p>
<p><code>gradlew "ofbizDebug --test component=entity --test
case=entity-tests"</code></p>
<h4 id="execute-an-integration-test-suite">Execute an integration test
suite</h4>
-<p>listens on port <strong>5005</strong></p>
<p><code>gradlew "ofbiz --test component=widget --test
suitename=org.apache.ofbiz.widget.test.WidgetMacroLibraryTests"</code></p>
<h4 id="execute-an-integration-test-suite-in-debug-mode">Execute an
integration test suite in debug mode</h4>
<p>listens on port <strong>5005</strong></p>
@@ -209,20 +214,94 @@
<p><code>gradlew cleanAll</code></p>
<h4 id="refresh-the-generated-artifacts">Refresh the generated artifacts</h4>
<p><code>gradlew clean build</code></p>
-<h4 id="create-a-custom-component-in-hot-deploy">Create a custom component in
hot-deploy</h4>
-<p><code>gradlew createComponent -PcomponentName=Custom
-PcomponentResourceName=Custom -PwebappName=customweb
-PbasePermission=OFBTOOLS,CUSTOM_SECURITY</code></p>
<h4 id="create-an-admin-user-account">Create an admin user account</h4>
<p>Create an admin user with login name MyUserName and default password with
value "ofbiz". Upon first login OFBiz will request changing the
default password</p>
<p><code>gradlew loadAdminUserLogin -PuserLoginId=MyUserName</code></p>
+<h4 id="compile-java-using-xlint-output">Compile Java using Xlint output</h4>
+<p>Xlint prints output of all warnings detected by the compiler</p>
+<p><code>gradlew -PXlint build</code></p>
+<h4 id="run-owasp-tool-to-identify-dependency-vulnerabilities-cves">Run OWASP
tool to identify dependency vulnerabilities (CVEs)</h4>
+<p>The below command activates a gradle plugin (OWASP) and Identifies and
reports known vulnerabilities (CVEs) in OFBiz library dependencies. This
command takes a long time to execute because it needs to download all plugin
dependencies and the CVE identification process is also time consuming</p>
+<p><code>gradlew -PenableOwasp dependencyCheck</code></p>
<h4 id="setup-eclipse-project-for-ofbiz">Setup eclipse project for OFBiz</h4>
<p>Thanks to some gradle magic, setting up OFBiz on eclipse is very easy. All
you need is to execute one command and then you can import the project to
eclipse. This command will generate the necessary <strong>.classpath</strong>
and <strong>.project</strong> files for eclipse.</p>
<p><code>gradlew eclipse</code></p>
<hr />
+<h2 id="ofbiz-plugin-system">OFBiz plugin system</h2>
+<p>OFBiz provides an extension mechanism through plugins. Plugins are standard
OFBiz components that reside in the specialpurpose directory. Plugins can be
added manually or fetched from a maven repository. The standard tasks for
managing plugins are listed below.</p>
+<blockquote>
+<p><em>Note</em>: OFBiz plugin versions follow <a
href="http://semver.org/";>Semantic Versioning 2.0.0</a></p>
+</blockquote>
+<h3 id="pull-download-and-install-a-plugin-automatically">Pull (download and
install) a plugin automatically</h3>
+<p>Download a plugin with all its dependencies (plugins) and install them
one-by-one starting with the dependencies and ending with the plugin itself.</p>
+<p><code>gradlew pullPlugin
-PdependencyId="org.apache.ofbiz.plugin:myplugin:0.1.0"</code></p>
+<p>If the plugin resides in a custom maven repository (not jcenter or
localhost) then you can use specify the repository using below command:</p>
+<p><code>gradlew pullPlugin
-PrepoUrl="http://www.example.com/custom-maven"
-PdependencyId="org.apache.ofbiz.plugin:myplugin:0.1.0"</code></p>
+<p>If you need username and password to access the custom repository:</p>
+<p><code>gradlew pullPlugin
-PrepoUrl="http://www.example.com/custom-maven" -PrepoUser=myuser
-PrepoPassword=mypassword
-PdependencyId="org.apache.ofbiz.plugin:myplugin:0.1.0"</code></p>
+<h3 id="install-a-plugin">Install a plugin</h3>
+<p>If you have a plugin called mycustomplugin and want to install it in OFBiz
follow the below instructions:</p>
+<ul>
+<li>Extract the plugin if it is compressed</li>
+<li>Place the extracted directory into /specialpurpose</li>
+<li>Run the below command</li>
+</ul>
+<p><code>gradlew installPlugin -PpluginId=myplugin</code></p>
+<p>The above commands achieve the following:</p>
+<ul>
+<li>add the plugin to /specialpurpose/component-load.xml</li>
+<li>executes the task "install" in the plugin's build.gradle file if
it exists</li>
+</ul>
+<h3 id="uninstall-a-plugin">Uninstall a plugin</h3>
+<p>If you have an existing plugin called mycustomplugin and you wish to
uninstall run the below command</p>
+<p><code>gradlew uninstallPlugin -PpluginId=myplugin</code></p>
+<p>The above commands achieve the following:</p>
+<ul>
+<li>executes the task "uninstall" in the plugin's build.gradle file
if it exists</li>
+<li>removes the plugin from /specialpurpose/component-load.xml</li>
+</ul>
+<h3 id="remove-a-plugin">Remove a plugin</h3>
+<p>Calls <strong>uninstallPlugin</strong> on an existing plugin and then
delete it from the file-system</p>
+<p><code>gradlew removePlugin -PpluginId=myplugin</code></p>
+<h3 id="create-a-new-plugin">Create a new plugin</h3>
+<p>Create a new plugin. The following project parameters are passed:</p>
+<ul>
+<li>pluginId: mandatory</li>
+<li>pluginResourceName: optional, default is the Capitalized value of
pluginId</li>
+<li>webappName: optional, default is the value of pluginId</li>
+<li>basePermission: optional, default is the UPPERCASE value of pluginId</li>
+</ul>
+<p><code>gradlew createPlugin -PpluginId=myplugin</code></p>
+<p><code>gradlew createPlugin -PpluginId=myplugin
-PpluginResourceName=MyPlugin -PwebappName=mypluginweb
-PbasePermission=MYSECURITY</code></p>
+<p>The above commands achieve the following:</p>
+<ul>
+<li>create a new plugin in /specialpurpose/myplugin</li>
+<li>add the plugin to /specialpurpose/component-load.xml</li>
+</ul>
+<h3 id="push-a-plugin-to-a-repository">Push a plugin to a repository</h3>
+<p>This task publishes an OFBiz plugin into a maven package and then uploads
it to a maven repository. Currently, pushing is limited to localhost maven
repository (work in progress). To push a plugin the following parameters are
passed:</p>
+<ul>
+<li>pluginId: mandatory</li>
+<li>groupId: optional, defaults to org.apache.ofbiz.plugin</li>
+<li>pluginVersion: optional, defaults to 0.1.0-SNAPSHOT</li>
+<li>pluginDescription: optional, defaults to "Publication of OFBiz plugin
${pluginId}"</li>
+</ul>
+<p><code>gradlew pushPlugin -PpluginId=myplugin</code></p>
+<p><code>gradlew pushPlugin -PpluginId=mycompany
-PpluginGroup=com.mycompany.ofbiz.plugin -PpluginVersion=1.2.3
-PpluginDescription="Introduce special functionality X"</code></p>
+<hr />
<h2 id="useful-tips">Useful Tips</h2>
<h3 id="gradle-tab-completion-on-unix-like-systems">Gradle tab-completion on
Unix-like systems:</h3>
<p>To get tab completion (auto complete gradle commands by pressing tab) you
can download the script from the below link and place it in the appropriate
location for your system.</p>
<p><a href="https://gist.github.com/nolanlawson/8694399";>Gradle tab
completion</a></p>
<p>For example, on debian based systems, you can use the following command:</p>
<p><code>sudo curl -L -s
https://gist.github.com/nolanlawson/8694399/raw/gradle-tab-completion.bash -o
/etc/bash_completion.d/gradle-tab-completion.bash</code></p>
+<h2 id="crypto-notice">Crypto notice</h2>
+<p>This distribution includes cryptographic software. The country in which you
currently reside may have restrictions on the import, possession, use, and/or
re-export to another country, of encryption software. BEFORE using any
encryption software, please check your country's laws, regulations and policies
concerning the import, possession, or use, and re-export of encryption
software, to see if this is permitted. See <a href="http://www.wassenaar.org/";
class="uri">http://www.wassenaar.org/</a> for more information.</p>
+<p>The U.S. Government Department of Commerce, Bureau of Industry and Security
(BIS), has classified this software as Export Commodity Control Number (ECCN)
5D002.C.1, which includes information security software using or performing
cryptographic functions with asymmetric algorithms. The form and manner of this
Apache Software Foundation distribution makes it eligible for export under the
License Exception ENC Technology Software Unrestricted (TSU) exception (see the
BIS Export Administration Regulations, Section 740.13) for both object code and
source code.</p>
+<p>The following provides more details on the included cryptographic
software:</p>
+<ul>
+<li>Various classes in OFBiz, including DesCrypt, HashCrypt, and BlowFishCrypt
use libraries from the Sun Java JDK API including java.security.* and
javax.crypto.* (the JCE, Java Cryptography Extensions API)</li>
+<li>Other classes such as HttpClient and various related ones use the JSSE
(Java Secure Sockets Extension) API</li>
+</ul>
</body>
</html>
