From 5ca48fdfd87af946a4ec1855b1bed3dc146c466e Mon Sep 17 00:00:00 2001
From: Matthew Swift <matthew.swift@forgerock.com>
Date: Wed, 17 Feb 2016 14:13:23 +0000
Subject: [PATCH] OPENDJSDK-86 - Replace README with Markdown README.md
---
/dev/null | 15 -----
opendj-sdk/README.md | 147 +++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 147 insertions(+), 15 deletions(-)
diff --git a/opendj-sdk/README b/opendj-sdk/README
deleted file mode 100644
index 0deff65..0000000
--- a/opendj-sdk/README
+++ /dev/null
@@ -1,15 +0,0 @@
-OpenDJ Ldap SDK
-
-This Maven project contains the OpenDJ Ldap Software Development Kit,
-All modules are 100% Java based and require Java 7.
-
-OpenDJ is a downstream build of the OpenDS project, with a different name
-to avoid trademark issues.
-
-Complete documentation for this product may be found online
-at http://www.forgerock.com/opendj.html.
-
-This product is made available under the Common Development and Distribution
-License (CDDL). The complete text for this license, and for alternate licenses
-of included components, may be found in the legal-notices directory.
-
diff --git a/opendj-sdk/README.md b/opendj-sdk/README.md
new file mode 100644
index 0000000..2c0897b
--- /dev/null
+++ b/opendj-sdk/README.md
@@ -0,0 +1,147 @@
+<!--
+ The contents of this file are subject to the terms of the Common Development and
+ Distribution License (the License). You may not use this file except in compliance with the
+ License.
+
+ You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
+ specific language governing permission and limitations under the License.
+
+ When distributing Covered Software, include this CDDL Header Notice in each file and include
+ the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
+ Header, with the fields enclosed by brackets [] replaced by your own identifying
+ information: "Portions copyright [year] [name of copyright owner]".
+
+ Copyright 2016 ForgeRock AS.
+ -->
+
+OpenDJ SDK
+==========
+
+The **OpenDJ LDAP SDK** provides a set of modern, developer-friendly Java APIs as part of the
+[OpenDJ](http://opendj.forgerock.org) product suite, which is actively maintained and supported by
+[ForgeRock](http://www.forgerock.com). The product suite includes the client SDK alongside command-line tools and
+sample code, a 100% pure Java directory server, and more. You can use **OpenDJ SDK** to create client applications
+for use with any server that complies with the
+[RFC 4510: LDAP - Technical Specification Road Map](http://tools.ietf.org/html/rfc4510).
+
+The **OpenDJ LDAP SDK** brings you easy-to-use connection management, connection pooling, load balancing, and all the
+standard LDAP operations to read and write directory entries. **OpenDJ LDAP SDK** also lets you build applications with
+capabilities defined in additional draft and experimental RFCs that are supported by modern LDAP servers.
+
+Documentation
+=============
+
+Javadoc for this module can be found [here](http://opendj.forgerock.org/opendj-core/apidocs/index.html). Read the
+[developer guide](http://opendj.forgerock.org/doc/dev-guide/index.html) for a deeper understanding of LDAP application
+development, as well as a detailed overview of LDAP itself.
+
+Get the OpenDJ LDAP SDK
+=======================
+
+You can start developing your LDAP applications now by obtaining the **OpenDJ LDAP SDK** using any of the following
+methods:
+
+Maven
+-----
+
+By far the simplest method is to develop your application using Maven and add the following settings to your pom.xml:
+
+```xml
+<repositories>
+ <repository>
+ <id>forgerock-staging-repository</id>
+ <name>ForgeRock Release Repository</name>
+ <url>http://maven.forgerock.org/repo/releases</url>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ </repository>
+ <repository>
+ <id>forgerock-snapshots-repository</id>
+ <name>ForgeRock Snapshot Repository</name>
+ <url>http://maven.forgerock.org/repo/snapshots</url>
+ <releases>
+ <enabled>false</enabled>
+ </releases>
+ </repository>
+</repositories>
+```
+
+The following dependencies will load both the [OpenDJ Core APIs](opendj-core) and the [OpenDJ Grizzly](opendj-grizzly)
+network transport. Remember to override the version according to your needs:
+
+```xml
+<dependencies>
+ <dependency>
+ <groupId>org.forgerock.opendj</groupId>
+ <artifactId>opendj-core</artifactId>
+ <version>3.0.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.forgerock.opendj</groupId>
+ <artifactId>opendj-grizzly</artifactId>
+ <version>3.0.0</version>
+ </dependency>
+</dependencies>
+```
+
+In some use-cases, such as developing LDAP unit tests or embedded LDAP applications, the network transport is not
+required, in which case you can simply declare a dependency on the OpenDJ core APIs:
+
+```xml
+<dependencies>
+ <dependency>
+ <groupId>org.forgerock.opendj</groupId>
+ <artifactId>opendj-core</artifactId>
+ <version>3.0.0</version>
+ </dependency>
+</dependencies>
+```
+
+Build it yourself
+-----------------
+
+You need `git` and `maven` in order to get the source code and build it:
+
+```bash
+git clone ssh://git@stash.forgerock.org:7999/opendj/opendj-sdk.git
+cd opendj-sdk
+mvn clean install
+```
+
+Getting started
+===============
+
+The following example shows how the **OpenDJ LDAP SDK** may be used to connect to a Directory Server, authenticate, and
+then perform a search. The search results are output as LDIF to the standard output:
+
+```java
+// Create an LDIF writer which will write the search results to stdout.
+final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
+
+// Connect and bind to the server.
+final LDAPConnectionFactory factory = new LDAPConnectionFactory(hostName, port);
+final Connection connection = factory.getConnection();
+connection.bind(userName, password.toCharArray());
+
+// Read the entries and output them as LDIF.
+final ConnectionEntryReader reader = connection.search(baseDN, scope, filter, attributes);
+while (reader.hasNext()) {
+ if (!reader.isReference()) {
+ final SearchResultEntry entry = reader.readEntry();
+ writer.writeComment("Search result entry: " + entry.getName());
+ writer.writeEntry(entry);
+ } else {
+ final SearchResultReference ref = reader.readReference();
+ writer.writeComment("Search result reference: " + ref.getURIs());
+ }
+}
+writer.flush();
+connection.close();
+```
+
+License
+=======
+
+**OpenDJ LDAP SDK** is licensed under [CDDL 1.0](legal-notices/CDDLv1_0.txt) (COMMON DEVELOPMENT AND DISTRIBUTION
+LICENSE Version 1.0)
--
Gitblit v1.10.0