Let’s not be negative, Maven when done right, is a beauty of its own and there are many advantages to it.

Objective & Targeted Readers

This series “Building and Deploying Java EE EAR with Maven to Java EE Application Server” will be written in parts. I’ll just begin with getting the build directory structure right (only for the Java EE EAR file for now), the next other parts will be about where to place the source codes and the deployment to major Application Servers like Glassfish, JBoss, WebLogic and any other major Application Server in the market that I can find a solution to deploy the EAR through Maven. I’ll try to document as much as short but precise as possible.

I’m writing this specifically for readers who are struggling with the migration from Ant to Maven. But having said that, this series will not be the introduction of Maven and what is it used for as there are already many documentations and web sites about that. But if you are a Java EE developer, have read and knew what Maven is, had at least seen what’s inside a pom.xml file but no idea how to meddle with it, or had at least explored its commands but having a hard time to just find a workable directory structure or ways to lay the proper foundation for your project (with unit tests and integration tests) and find it difficult to even deploy your project to a specific App Server, the articles in this series is definitely for you. Let’s begin.

Introduction to Maven’s Java EE EAR Directory Structure

Aligning Expectations

Unlike Ant, where by you could freely script the build.xml file to accommodate your development and deployment requirements – asking it to pick up and pack your files from whichever source directories, resource directories or other facilitating file directories that you’ve made and specified; Maven on the other hand works with predefined directory structure specified by Maven as it goes along with the song “convention over configuration”. The POM.xml file in Maven pretty much defines the project structure, which dependency (external jar(s)/libraries from other projects including open source ones) from the local or remote repository that it needs, plus plugins that the project would require. A Maven project will include modules and sub-modules. As I have mentioned earlier, Maven is more than a build tool, it’s a project build, maintenance and management tool.

Maven’s Java EE EAR Directory Structure

Maven works with predefined directory structure for your source codes, application resource files, unit test(s), integration-test and even reports. This is a good thing considering that it standardizes the directory path and naming convention so that other developers who are currently or in future maintain the software project will know where to look for the files when they are involve with the project.

To give you an idea, I will build a demo project for this tutorial, let’s call it DummyDemoJavaEE5 (you may use this for your Java EE 6 application as well). In this demo project, it will include the following modules:

• DummyDemo-ejb - a module where you put your EJBs (codes and unit tests)
• DummyDemo-web – a module for web presto files like html, css, javascripts and front controller classes (codes and unit tests)
• DummyDemo-api – a module for common used codes such as utilities, helpers, tools etc. specifically for the project (codes and unit tests)
• DummyDemo-appclient – a module for Enterprise App Client (codes and unit tests)
• DummyDemo-ear – a module specifically to package everything to an EAR file for deployment and to access the app server
• integration-test – Lastly, a module solely existed for integration tests (not unit tests). This is where you place all of the integration test codes in this module.

You may not use every module in your project as describe as the above, for example, some projects will not need the Enterprise App Client. You may exclude any of them in your actual project. But for now, this is quite a good repertoire of modules for a Java EE project. The below shows the directory structure for the mentioned modules. Do take note on the folders for your source codes, unit tests and integration tests, at the same time, where to place the pom.xml for their respective modules…this is how it works in Maven. You may create them manually or you can use one of the handy command in Maven call archetype:generate, which we’ll go through it later.

** Directories are highlighted in BOLD

DummyDemoJavaEE5 (The root folder)
	|
	|---project (contains the core enterprise application codes with the below modules)
	|		|
	|		|---DummyDemo-ear (used for producing the EAR file - no codes here please...)
	|		|		|
	|		|		|---pom.xml (The pom file that defines what is to be included in the EAR)
	|		|
	|		|---DummyDemo-ejb (contains codes for EJBs)
	|		|		|---src
	|		|		|	|---main
	|		|		|	|	|---java (this is the folder where you should put your
	|		|		|	|			  EJB codes - with package folders)
	|		|		|	|---test
	|		|		|		|---java (this is the folder where you should put your
	|		|		|				  unit test that has to do with DummyDemo-ejb
	|		|		|				  - with package folders)
	|		|		|
	|		|		|---pom.xml (The pom file that defines the DummyDemo-ejb module as packaging
	|		|					 type "ejb" with the needed maven dependencies)
	|		|
	|		|---DummyDemo-web (contains web presto stuff like JSP, JSF, CSS, JS, etc.)
	|		|		|---src
	|		|		|	|---main
	|		|		|	|	|---java (this is the folder where you should put your
	|		|		|	|	|		  servlet, JSF or MVC related codes - with package folders)
	|		|		|	|	|
	|		|		|	|	|---webapp (this is the folder for the JSPs, xhtml, css, javascripts, etc.)
	|		|		|	|			|---WEB-INF
	|		|		|	|					|---web.xml (here's you should define your web.xml file)
	|		|		|	|
	|		|		|	|---test
	|		|		|		|---java (this is the folder where you should put your
	|		|		|				  unit test that has to do with the classes in DummyDemo-web
	|		|		|				  - with package folders)
	|		|		|
	|		|		|---pom.xml (The pom file that defines the DummyDemo-web module as packaging
	|		|					 type "war" with the needed maven dependencies)
	|		|
	|		|---DummyDemo-api (contains commonly used classes as part of the library)
	|		|		|---src
	|		|		|	|---main
	|		|		|	|	|---java (this is the folder where you should put your
	|		|		|	|			  codes e.g. utility codes, parsers, etc. - with package folders)
	|		|		|	|---test
	|		|		|		|---java (this is the folder where you should put your unit test
	|		|		|				  that has to do with DummyDemo-api - with package folders)
	|		|		|
	|		|		|---pom.xml (The pom file that defines the DummyDemo-api module
	|		|					 with the needed maven dependencies)
	|		|
	|		|---DummyDemo-appclient (contains codes for Enterprise Application Client)
	|		|		|---src
	|		|		|	|---main
	|		|		|	|	|---java (this is the folder where you should put your
	|		|		|	|			  codes for the Enterprise Application Client - with package folders)
	|		|		|	|---test
	|		|		|		|---java (this is the folder where you should put your unit test
	|		|		|				  that has to do with DummyDemo-apiclient - with package folders)
	|		|		|
	|		|		|---pom.xml (The pom file that defines the DummyDemo-appclient module as
	|		|					 packaging type "app-client" with the needed maven depencencies)
	|		|
	|		|---pom.xml (pom file for project folder)
	|		
	|---integration-test (contains only integration test classes)
	|		|---src
	|		|	|---test
	|		|		|---java (this is the folder where you should put your
	|		|				  integration tests - with package folders)
	|		|
	|		|---pom.xml (The pom file that defines the integration-test module as
	|					 with the needed maven dependencies for running integration tests)
	|
	|---pom.xml (root pom file)

These directories are what you should expect from a decent Java EE project being packaged in an EAR as a target deployment file format later. Since the name of the project is DummyDemoJavaEE5, let’s make DummyProbeJavaEE5 as the root folder for the rest of the sub-modules. Next, under the DummyProbeJavaEE5 root project folder, what we could do is to have two separated folders, one is called project, which consists of the core contents of the modules (that includes source codes, resource files and unit tests – yes, only unit tests, not integration tests) and the other folder is called integration-test, which only host integration test codes as the name implies.

This is a clean separation and why do we do that? Because we would not want the integration test codes to be part of the build life cycle of the core project modules every time when we need to compile and deploy to the app servers; but, when the need arise for integration tests to be executed, it could be invoked independently. Even though it is separated, the project codes’ dependency for the integration test is not broken as we can define that in the pom.xml file. I’ll leave the discussion of the contents of the pom.xml files to the next part of the series.

Creating The Directories Through Maven archetype:generate Command

The Maven’s archetype:generate command will pre-generate the directory modules, sub-modules and their respective pom.xml files. This will save you time and reduce much error against manual creation. Of course, this is not fool proof as the pom.xml files will have to be edited later to include dependencies and other plugins that are necessary.

To use Maven’s archetype:generate command for creating the project structure above, follow the below steps. Before you start, just make sure that the maven’s mvn command is in the path. Use the command prompt or terminal to carry out the below steps.

Creating the “DummyDemoJavaEE5″ project root directory

1. Since the demo project name is DummyDemoJavaEE5, log onto the terminal and type “mvn archetype:generate“. This command will list all of the archetypes available in Maven and from version 3 onwards, it has more than 600 archetypes to choose from.

   What you need to do now is to filter the archetype for root directory, to do this, just type: “org.codehaus.mojo.archetypes:pom-root” at the prompt, it shall filter only one archetype which is org.codehaus.mojo.archetypes:pom-root. It will return something like this:
   

   1: remote -> org.codehaus.mojo.archetypes:pom-root (Root project archetype for creating multi module
   projects)
   

   type “1″ to to proceed.

2. Next, it will ask you to choose the version of the archetype, just accept, the default, which will always refer to the latest version.
3. Next, it will ask you to enter the groupId. The groupId is a unique name that identifies your project across all projects that all modules within this project should share as common. I’m going to use “com.developerscrappad” here as an example, you may use your company’s package name such as com.mycompany, etc. as the groupId. Once you’ve decided on this, it has to be the same across the any modules that you want to have in this project.
4. After keying in the groupId, it will then ask you for the artifactId. The artifactId is the name of the project/module, if not, it is commonly use as the name of the jar file, the war file or the ear file. Since we are creating the root directory for a new project, just enter the name of the project “DummyDemoJavaEE5″ as the artifactId.
5. Next, it will ask for version number, follow by the package name defaulted to the groupId as you have entered, just accept them by default and the root directory structure will be created. Once done, you should be able to see the “DummyDemoJavaEE5″ directory and within it, it will have a pom.xml file.

The archetype that you’ve used just now is to create the root pom (Project Object Model). The root pom is always used to encapsulate any modules within it and make it look as a whole. A root pom can consists of other root pom(s) and other modules within the directory.

Creating the “project” directory

Now that you know how to use the archetype:generate command, we still need to create the rest of the directories and modules. Next, we need to create the project directory, which is where you put all of the module codes in it. Please change your working directory into DummyDemoJavaEE5 ( <path>/DummyDemoJavaEE5/ ) and do the same like what you did to create the root project directory DummyDemoJavaEE5. Do use the same archetype as you did and follow the below parameters:

• archetype: org.codehaus.mojo.archetypes:pom-root
• groupId: com.developerscrappad
• artifactId: project
• Version & package: accept the default values

Once done, you should be able to see a generated pom.xml within the project directory.

Creating the “DummyDemo-ejb” module directory for EJBs and other back-end codes

Next, change the working directory into project directory ( <path>/DummyDemoJavaEE5/project/ ). Now, we’ll make a module specifically for your EJBs. This module is specifically used to place your entity classes, session beans, message-driven beans and other back-end related codes. To achieve this, we’ll have to use another archetype call org.codehaus.mojo.archetypes:ejb-jee5 instead of pom-root (yes, you can use this for Java EE 6). Follow the below:

1. Once you are in the <path>/DummyDemoJavaEE5/project/ directory, type “mvn archetype:generate” and type the filter “org.codehaus.mojo.archetypes:ejb-jee5“:
   

   1: remote -> org.codehaus.mojo.archetypes:ejb-jee5 (-)
   

   Just type “1″, the number of the selection.

2. For the rest of the parameters, just follow the below:
   • groupId: com.developerscrappad
   • artifactId: DummyDemo-ejb
   • Version & package: accept the default values

Once done, you should be able to see the DummuDemo-ejb directory ( <path>/DummyDemoJavaEE5/project/DummyDemo-ejb/ ) and within it, the pom.xml file will be created as well. You may have multiple EJB modules using the same way to generate them if you decide to introduce separation of business process instead of lumping all EJBs into one module in your future project.

Creating the “DummyDemo-api” module directory for commonly used classes that pack as a jar/library

Sometimes, you may have some commonly used classes through out the project such as utility classes, helpers, tools or parsers that you want to put them into a jar file so that other modules could use it. Just follow the below:

1. In the working directory of project ( <path>/DummyDemoJavaEE5/project/ ) perform the “mvn archetype:generate” command.
2. When ask to filter the archetype, type: “org.apache.maven.archetypes:maven-archetype-quickstart“, you should get something like:
   

   1: remote -> org.apache.maven.archetypes:maven-archetype-quickstart (An archetype which contains
   a sample Maven project.)
   

   just select it.

3. For the rest of the parameters, just key in the below:
   • groupId: com.developerscrappad
   • artifactId: DummyDemo-api
   • Version & package: accept the default values

Once done, the module directory DummyDemo-api will be created with the pom.xml file inside of it. This is the place where you put your commonly used codes.

Creating the “DummyDemo-web” module directory for JSFs, JSPs, MVCs and other web presentation related files

The DummyDemo-web is the web application module for the project. To create this, please make sure that the working directory is still on project ( <path>/DummyDemoJavaEE5/project/ ). We need to use the org.codehaus.mojo.archetypes:webapp-jee5 archetype. Just create this with the archetype:generate command, filter the archetype and you should see something like:

1: remote -> org.codehaus.mojo.archetypes:webapp-jee5 (-)

• archetype: org.codehaus.mojo.archetypes:webapp-jee5
• groupId: com.developerscrappad
• artifactId: DummyDemo-web
• Version & package: accept the default values

Once the module was created, the pom.xml file will be generated and the rest of the module directory structure specifically for JEE webapp, that includes the WEB-INF directory, the sample web.xml and a sample index.jsp file.

Creating the “DummyDemo-appclient” module directory for Enterprise Application Client

Not many enterprise application will need an Application Client, but if you need it in your project, these are the steps to create the Enterprise Application Client module. Here, let’s call it DummyDemo-appclient. Do this in the project ( <path>/DummyDemoJavaEE5/project/ ) working directory, we need to use the archetype call “org.codehaus.mojo.archetypes:appclient-jee5“. Just use the archetype:generate command the same way with the details below:

• archetype: org.codehaus.mojo.archetypes:appclient-jee5
• groupId: com.developerscrappad
• artifactId: DummyDemo-appclient
• Version & package: accept the default values

Once completed, not only that the pom.xml file will be generated, but this module includes a sample Main.java file as the main class for the Enterprise Application Client.

Creating the “DummyDemo-ear” module for packing the EAR file

Now that we have the rest of the Java EE core modules, it is time to create the DummyDemo-ear module solely for packaging the EAR file and it is also in this module that we will define the deployment instructions in the pom.xml file. I’ll leave the discussion in the later part of the series, because different app server will require different configuration.

Anyway, to create the DummyDemo-ear module, we need to use the org.codehaus.mojo.archetypes:ear-jee5 archetype. In the working directory of project ( <path>/DummyDemoJavaEE5/project/ ), just use the “mvn archetype:generate” command with the below details:

• archetype: org.codehaus.mojo.archetypes:ear-jee5
• groupId: com.developerscrappad
• artifactId: DummyDemo-ear
• Version & package: accept the default values

There is nothing much to explore inside the DummyDemo-ear module directory for now after creating. But nevertheless, this module is important for deployment later on.

Creating the “integration-test” module for, well…integration tests

Lastly, we’ll now create the integration-test module, which is solely for any integration tests classes. You may place your unit tests files in the previously created modules, but as time passes, I find that having a separate module solely for integration tests will be much better as tests could be run independently without having to induce skip flags to maven and will not run prematurely before the the EAR is being deployed to the application server.

Creating the integration-test module is easy. Just change the working directory out from the project directory and back to the DummyDemoJavaEE5 root folder ( <path>/DummyDemoJavaEE5/ ), use the “org.apache.maven.archetypes:maven-archetype-quickstart” archetype as you execute the “mvn archetype:generate” command. As for the rest of the parameters, the details are below:

• archetype: org.apache.maven.archetypes:maven-archetype-quickstart
• groupId: com.developerscrappad
• artifactId: integration-test
• Version & package: accept the default values

Once complete, you have a separate integration-test module solely for your integration test classes. In fact, you may use the same approach to create a functional test module to run Selenium related tests if you wish for your future projects.

To Be Continued…

If you have followed through the above steps, you should be able to produce all of the module layout of the project, plus the module for integration-test. In my opinion, using Maven’s archetype:generate command to generate the project and module layout is very much faster than by doing it manually. It generates the pom.xml file, although it is not complete, still it is much faster and less error than crafting it by your own.

We are far from finish. I will leave the discussion of what contents to be included in the pom.xml file in the next part of the series. As for the next part, I’ll be writing about where to put the codes and what are the necessary plugins and dependency that is to be included in the pom.xml files. So, stay tuned.

What is Object-GUID

The objectGUID is the attribute that holds the Global Unique Identity Code of the object that resides in the Active Directory. According to Microsoft Technet’s documentation, the uniqueness of the ID does not only limits itself across the enterprise but it is unique throughout the entire globe. It is a 128-bit value, so expect nothing less. Nevertheless, Object-GUID is how Active Directory uses to identify the object, whether it is of user/person or group or others. For this entire article, we’ll be dealing with Object-GUID specifically for a User/INetPerson.

What is the Purpose of Object-GUID?

As mentioned, the Object-GUID is a unique identity for a user/person or a group and other objects in the Active Directory. Not only that it is unique, it is unchangeable and non-volatile throughout the environment. This is something good. Why? Let’s say if the Active Directory has a user by the name (CN) of “Adam Bristol” with the userPrincipalName as “adambristol@developerscrappad.com”; if on one fine day the Adaministrator decides to change the logon name (userPrincipalName) to “adambristol-20110908@developerscrappad.com”, even the object is the same but if you have an application that uses the previous userPrincipalName to locate the same user record, it will yield nothing. So therefore, GUID is the way to go to use to locate and bind an object, because it is permanent and non-changeable; it is like the primary key used in databases, likewise GUID serves as the “primary key” in analogy in the Active Directory.

Where Can We Use Object-GUID?

If your application is tightly coupled with Active Directory as a means to gain access to user information, you can use GUID to directly locate the user without going through the LDAP queries with search filter; even at times when LDAP search is necessary, you may skip the lengthy query syntax just by querying the GUID alone, you should be able to object the specific user object right on the dot.

If you ever need some sort of key data or unique identifier to represent a user as a form of primary key to be kept in the database so that other tables could reference it as a foreign key, GUID is the best fitted value to be used for this purpose. Like wise, in my opinion, it is not recommended to have sAMAccountName or userPrincipalName as the identifier of user in both the context of LDAP lookup and database primary/foreign key referential when it comes to developing custom application with Active Directory & database pairing.

How To Obtain A User’s objectGUID From Windows Active Directory

Now, assuming that in the Active Directory, we have a fictional user with the logon name “adambristol” under the domain name of “developerscrappad.com”; you may obtain the objectGUID attribute value shown below:

Hashtable<String, String> env = new Hashtable<String, String>();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://10.0.0.1:389");   //Just change this to the actual IP and Port
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put("java.naming.ldap.attributes.binary", "objectGUID");    //Important!
env.put(Context.SECURITY_PRINCIPAL, "adambristol@developerscrappad.com");
env.put(Context.SECURITY_CREDENTIALS, "passwd1234");
 
DirContext ctx;
 
try {
    //Authenticate the logon user
    ctx = new InitialDirContext(env);
 
    //Start checking if the user is within the organization unit(s)
    String searchBase = "DC=developerscrappad,DC=com";
    String searchFilter = "(&(objectClass=person)(userPrincipalName=adambristol@developerscrappad.com))";
    String[] returningAttrs = {"objectGUID"};
    SearchControls sCtrl = new SearchControls();
    sCtrl.setSearchScope(SearchControls.SUBTREE_SCOPE);
    sCtrl.setReturningAttributes(returningAttrs);
 
    NamingEnumeration<SearchResult> answer = ctx.search(searchBase, searchFilter, sCtrl);
 
    if (answer.hasMore()) {
        SearchResult sr = answer.next();
        byte[] guid = (byte[]) sr.getAttributes().get("objectGUID").get();
 
        // Do something with guid
    }
} catch (NamingException ex) {
    // Do something with the exception...
}

Notice that when we define the environment “env” variable, which is an instance of java.util.Hastable, besides all the regular properties and value that you need to put into the Hashtable, do remember to have this as well:

env.put("java.naming.ldap.attributes.binary", "objectGUID");

This property value is important because usually when we traverse the directory tree, attribute value objects will be returned as an instance of java.lang.String. Buy having the line above, it will return the attribute value object specifically for attribute “objectGUID” as an instance of byte [] instead (the rest of the attribute values will still remain as java.lang.String).

IMPORTANT Note:
For line 27, PLEASE DO NOTE CODE THE BELOW:

byte[] guid = sr.getAttributes().get("objectGUID").get().toString().getBytes();

as turning it to String then to bytes again will adulterate the original byte values.

Now, if you check the guid[] array’s size, you’ll realized that the length value is 16 (128-bits). Every GUID will have this fix amount of byte array size. Let’s move on to the below and see what we can do with the chunk of bytes drawn. From here on, we’ll have to deal with the guid from byte to byte (8-bit).

Decoding Method 1: Binding String – What Is It and Where To Use It?

The Binding String is a string with specific format which is being use to immediately bind the user object and gain direct access to the attributes of it without going through the tedious nitty-gritty task of defining the LDAP searchBase and searchFilter value to specifying the SearchControl and other processing resources of searching through the Active Directory tree.

The format of a Binding GUID String will look something like the below:

<GUID=ac642e6e-6ab5-425a-bcc9-9f5067d46e3f>

Notice that after the prefix “<GUID=”, what follows is a series of double digit Hex values with dashes “-” in between. Some folks call it Dashed String to simplify things. Nevertheless, the Dashed String is what we desire to construct so that we could form the the Binding String later.

How To Decode objectGUID To Dashed String?

To decode raw binary data from GUID to Dashed String, we should arrange the individual specific byte array slot to the below format and TURN EACH array value to double digit Hex representation from the unsigned value of the byte.

Dashed String Format Sequence:

The below are the byte array index sequence (no space):

[3] [2] [1] [0] - [5] [4] - [7] [6] - [8] [9] - [10] [11] [12] [13] [14] [15]

Introducing Bit Masking

It is tempting to convert the byte directly to Hex string by invoking e.g. Integer.toHexString((int)guid[0]), unfortunately, by the nature of Java, this might not produce the right represented value as you have to remember that the byte data type in Java is a signed data type, therefore, there is a possibility that output may be a negative integer value. In order to prevent that, we need a to implement a layer of bit mask. Bit masking is a technique to filter the byte so that it could prevent the sign bit extension from clobbering the higher bytes.

For example, in order to convert the byte to int, which is to be used as an argument for Integer.toHexString(), do the following:

int maskedValue = (int) guid[0] & 0xff;
String hexString = Integer.toHexString(maskedValue);

The above is just an example of bit masking and we’ll be using this technique (not the exact code) for the rest of the decoding process.

How To Decode The Bytes

If you had follow the codes above to obtain the “guid” byte array, here’s the step-by-step process of decoding each byte within the array:

1. First, know the sequence of the byte index that forms the Dashed String. Just refer to the above.
2. Next, apply bit masking to each and every single byte value accessed in the array.
3. Follow by converting to the Hex representation of the value.
4. Just make sure that the Hex value is a double digit value, meaning instead of “A”, it should be “0A”
5. Lastely, form the Binding String in the syntax format of “<GUID=dashed-string-value>”

To do this in Java, just follow the codes below:

public static String convertToBindingString(byte[] objectGUID) {
    StringBuilder displayStr = new StringBuilder();
 
    displayStr.append("<GUID=");
    displayStr.append(convertToDashedString(objectGUID));
    displayStr.append(">");
 
    return displayStr.toString();
}
 
public static String convertToDashedString(byte[] objectGUID) {
    StringBuilder displayStr = new StringBuilder();
 
    displayStr.append(prefixZeros((int) objectGUID[3] & 0xFF));
    displayStr.append(prefixZeros((int) objectGUID[2] & 0xFF));
    displayStr.append(prefixZeros((int) objectGUID[1] & 0xFF));
    displayStr.append(prefixZeros((int) objectGUID[0] & 0xFF));
    displayStr.append("-");
    displayStr.append(prefixZeros((int) objectGUID[5] & 0xFF));
    displayStr.append(prefixZeros((int) objectGUID[4] & 0xFF));
    displayStr.append("-");
    displayStr.append(prefixZeros((int) objectGUID[7] & 0xFF));
    displayStr.append(prefixZeros((int) objectGUID[6] & 0xFF));
    displayStr.append("-");
    displayStr.append(prefixZeros((int) objectGUID[8] & 0xFF));
    displayStr.append(prefixZeros((int) objectGUID[9] & 0xFF));
    displayStr.append("-");
    displayStr.append(prefixZeros((int) objectGUID[10] & 0xFF));
    displayStr.append(prefixZeros((int) objectGUID[11] & 0xFF));
    displayStr.append(prefixZeros((int) objectGUID[12] & 0xFF));
    displayStr.append(prefixZeros((int) objectGUID[13] & 0xFF));
    displayStr.append(prefixZeros((int) objectGUID[14] & 0xFF));
    displayStr.append(prefixZeros((int) objectGUID[15] & 0xFF));
 
    return displayStr.toString();
}
 
private static String prefixZeros(int value) {
    if (value <= 0xF) {
        StringBuilder sb = new StringBuilder("0");
        sb.append(Integer.toHexString(value));
 
        return sb.toString();
 
    } else {
        return Integer.toHexString(value);
    }
}

Codes Explanation:
The prefixZeros() method is used to convert the int value to Hex value and adding a “0″ in front of the Hex character is it is only of a single digit and thus making it a double Hex value.

The core is in the convertToDashedString() method where it takes the byte array of the objectGUID value as an argument, access the byte array index individually according to the dashed-string sequence, perform bit mask on each and every byte, send it to the prefixZeros() method, then form the string sequence.

Lastly, convertToBindingString() method is more like a wrapper where it takes the objectGUID byte array, pass it to method convertToDashedString() and add both prefix “<GUID=”and postfix “>” to the result that was return from the convertToDashedString() method.

How To Use Binding String To Bind An Object?

Once you have successfully converted the raw byte array gotten from the objectGUID attribute to the Binding String format, you may always directly bind a user with the following codes:

// After initializing the ctx object which is an instance of DirContext...
 
String bindingString = "<GUID=ac642e6e-6ab5-425a-bcc9-9f5067d46e3f>";
Attributes attrs = ctx.getAttributes(bindingString);
 
// Then do something with the attrs, for example...
NamingEnumeration<String> ids = attrs.getIDs();
 
while (ids.hasMore()) {
    String id = ids.next();
    Object value = attrs.get(id).get();
 
    System.out.println("Attribute: " + id + ", Value: " + value);
}

This is how you can directly bind the user object and obtain all of its attributes immediately. The object binding through Binding String is the easiest, if not, the fastest way of direct accessing the user in the Active Directory without needing to know the OU or the userPrincipalName.

** Personally, when I develop application that requires Active Directory access and a database for other application interest, I’ll keep the Binding String as a primary key in my user table as it could be used to referenced by other tables and make reference to the Active Directory.

Decoding Method 2: Byte String – What Is It and Where To Use It?

Suppose that if you need a way to search of a particular user through LDAP query using the SearchControl object or through other LDAP tools, it will be quite difficult to use the raw byte value of the objectGUID as the query parameter as the query string will require another format of the objectGUID. So here, I’ll show you how to decode the objectGUID byte array to form a Byte String (a.k.a. Octet String).

How To Decode To Byte String?

To decode the guid byte array to byte string, we need to loop through the array, convert the bytes to double digit Hex representation and arrange it in such format with the front slash as a prefix for each byte (without space):

\ [0] \ [1] \ [2] \ [3] \ [4] \ [5] \ [6] \ [7] \ [8] \ [9] \ [10] \ [11] \ [12] \ [13] \ [14] \ [15]

Decoding Procedure

By using the same byte array guid variable as we’ve gotten from the codes above, just follow the below process to decode the bytes to form the Byte String:

1. Write a while loop for loop through the guid byte array.
2. For every byte in the array, make sure to perform a bit mask and convert it to Hex string by invoking Integer.toHexString() method.
3. Once the Hex string is gotten, just check it and prefix the front with “0″ for single digit to make it as a double digit Hex string.
4. Build the final Byte String with the front slash “\” prefixed on every Hex string value.

This is very simple and straight forward. Here are the Java codes to perform the mentioned process:

public static String convertToByteString(byte[] objectGUID) {
    StringBuilder result = new StringBuilder();
 
    for (int i = 0; i < objectGUID.length; i++) {
        String transformed = prefixZeros((int) objectGUID[i] & 0xFF);
        result.append("\\");
        result.append(transformed);
    }
 
    return result.toString();
}
 
private static String prefixZeros(int value) {
    if (value <= 0xF) {
        StringBuilder sb = new StringBuilder("0");
        sb.append(Integer.toHexString(value));
 
        return sb.toString();
 
    } else {
        return Integer.toHexString(value);
    }
}

How To Use The Byte String To Search For An Object?

As mentioned, the Byte String is used for LDAP query instead to bind an object directly from the Active Directory. For example, after getting the raw bytes of the objectGUID from a fictional user with userPrincipalName of “adambristol@developerscrappad.com”, and once the bytes were converted to Byte String, the Byte String output will be something like the below:

\6e\2e\64\ac\b5\6a\5a\42\bc\c9\9f\50\67\d4\6e\3f

Next, in order to construct a property LDAP search query with the objectGUID parameter value properly defined, the search query should look like the below example:

(&(objectClass=person)(objectGUID=\6e\2e\64\ac\b5\6a\5a\42\bc\c9\9f\50\67\d4\6e\3f))

This is how we put the Byte String in to good use for LDAP searching. By putting it in Java codes, it should very well be like the below:

// After initializing the ctx object, which is an instance of DirContext
 
String searchBase = "DC=developerscrappad,DC=com";
String searchFilter = "(&(objectClass=person)(objectGUID=\\6e\\2e\\64\\ac\\b5\\6a\\5a\\42\\bc\\c9\\9f\\50\\67\\d4\\6e\\3f))";
SearchControls sCtrl = new SearchControls();
sCtrl.setSearchScope(SearchControls.SUBTREE_SCOPE);
 
NamingEnumeration<SearchResult> answer = ctx.search(searchBase, searchFilter, sCtrl);
 
// Do something with the search result...
if (answer.hasMore()) {
    SearchResult sr = answer.next();
    Attributes attrs = sr.getAttributes();
 
    NamingEnumeration<String> ids = attrs.getIDs();
 
    while (ids.hasMore()) {
        String id = ids.next();
        Object value = attrs.get(id).get();
 
        System.out.println("Attribute: " + id + ", Value: " + value);
    }
}

The Byte String was used for the searchFilter and for every front slash “\”, please remember to escape it. This sums up the construction of Byte String and how to put it in use when you need to perform the LDAP search for a particular user.

Summary

I hope these 2 ways of decoding the objectGUID value written here could help you to approach your Active Directory user access and management through your Java application in a more confident and efficient way. I have written a class with the codes below at your disposal to simplify the objectGUID decoding experience:

public class ObjectGUID_Tools {
 
    public static String convertToByteString(byte[] objectGUID) {
        StringBuilder result = new StringBuilder();
 
        for (int i = 0; i < objectGUID.length; i++) {
            String transformed = prefixZeros((int) objectGUID[i] & 0xFF);
            result.append("\\");
            result.append(transformed);
        }
 
        return result.toString();
    }
 
    public static String convertToBindingString(byte[] objectGUID) {
        StringBuilder displayStr = new StringBuilder();
 
        displayStr.append("<GUID=");
        displayStr.append(convertToDashedString(objectGUID));
        displayStr.append(">");
 
        return displayStr.toString();
    }
 
    public static String convertToDashedString(byte[] objectGUID) {
        StringBuilder displayStr = new StringBuilder();
 
        displayStr.append(prefixZeros((int) objectGUID[3] & 0xFF));
        displayStr.append(prefixZeros((int) objectGUID[2] & 0xFF));
        displayStr.append(prefixZeros((int) objectGUID[1] & 0xFF));
        displayStr.append(prefixZeros((int) objectGUID[0] & 0xFF));
        displayStr.append("-");
        displayStr.append(prefixZeros((int) objectGUID[5] & 0xFF));
        displayStr.append(prefixZeros((int) objectGUID[4] & 0xFF));
        displayStr.append("-");
        displayStr.append(prefixZeros((int) objectGUID[7] & 0xFF));
        displayStr.append(prefixZeros((int) objectGUID[6] & 0xFF));
        displayStr.append("-");
        displayStr.append(prefixZeros((int) objectGUID[8] & 0xFF));
        displayStr.append(prefixZeros((int) objectGUID[9] & 0xFF));
        displayStr.append("-");
        displayStr.append(prefixZeros((int) objectGUID[10] & 0xFF));
        displayStr.append(prefixZeros((int) objectGUID[11] & 0xFF));
        displayStr.append(prefixZeros((int) objectGUID[12] & 0xFF));
        displayStr.append(prefixZeros((int) objectGUID[13] & 0xFF));
        displayStr.append(prefixZeros((int) objectGUID[14] & 0xFF));
        displayStr.append(prefixZeros((int) objectGUID[15] & 0xFF));
 
        return displayStr.toString();
    }
 
    private static String prefixZeros(int value) {
        if (value <= 0xF) {
            StringBuilder sb = new StringBuilder("0");
            sb.append(Integer.toHexString(value));
 
            return sb.toString();
 
        } else {
            return Integer.toHexString(value);
        }
    }
}

Best of effort to you and thank you for reading.

Related Articles:

• Java JNDI/LDAP: Windows Active Directory Authentication, Organizational Unit, Group & Other Information Access
• Quick Note: Unable To Perform LDAP Wildcard “*” Search On Windows Active Directory

(&(objectClass=person)(userPrincipalName=username@mydomain.com)(memberOf=Some Group*))

You wouldn’t be able to get any result from this search. Therefore, if you are developing software solution which requires wildcard searching on DN typed attribute, you need to find a work around.

How To Know If An Attribute Is Of Type Distinguished Name?

This is very simple for Windows Active Directory. Just perform the below as the:

1. In the command prompt or just type “mmc /a” and press “Enter”. You may do this with the Start button -> Run -> “mmc /a” as well. This command will bring out Microsoft Management Console.
2. At the console, Click File -> Add/Remove Snap-ins.
3. In the “Available Span-ins” selection list, select Active Directory Schema, then click on the “Add >” button. Then click “OK“.
4. Now, Active Directory Schema should appear as part of the Console Root tree. Expend it and click on the “Attributes” folder. You should see all of the attributes in the table.
5. In the attributes table, just click on the “Syntax” column header to sort it, scroll down until you see attributes with syntax of “Distinguished Name” like the picture below:
   

The attributes list that carries the type “Distinguished Name” in the Syntax column are the ones that could not be search with partial wildcard “*” search.

Hope it helps.

Related Articles:

• Java JNDI/LDAP: Windows Active Directory Authentication, Organizational Unit, Group & Other Information Access
• Java LDAP/JNDI: 2 Ways Of Decoding And Using The objectGUID From Windows Active Directory

Tools Needed

Besides your IDE or your TextPad for your Java codes, you might need LDAP tools to explore and traverse the active directory for some insights. If you are using Eclipse IDE, you may want to consider Apache’s Directory Studio found at http://directory.apache.org/studio/. For Netbeans users, you may want to consider the LDAP Explorer plugin which can be found at http://plugins.netbeans.org/plugin/25684/ldap-explorer.

A Story Of A Company

Here, I’ll use a fictional company with fictional Active Directory structure that brings us to our code samples later which then enables us to authenticate and the checking of privileges to access certain feature of your application according to the user’s organizational unit, groups, department or even the job title. Let’s say, this fictional company by the name Developer’s Scrappad has both the office in Seattle, US and in London, UK. In both of these regional offices, both have a Sales & Marketing department and there are active staffs within these departments. I have installed a fresh copy of Windows 2003 Server on my test machine and I have enabled Active Directory service and created the root domain as “developerscrappad.com“.

The US Office Structure

Just right after the root domain, I have created an Organizational Unit (OU) call “US” and within the “US” OU, I have created another OU called “Seattle Office“. I have created some fictional staff in the Sales & Marketing department and you may find their details listed in the below table:

The UK Office Structure

As for UK’s London Office, I have created an OU call “UK” just right below the root domain. Within the “UK” OU, I have created another OU call “London Office“. The table below shows the list of staff (of INetOrgPerson type) that resides in “London Office” OU (there’s only 2 of them):

Making Things Interesting With Groups

Now, developerscrappad.com is pretty focus in getting their company presence and products marketed through social media. As a result, they’ve formed a group call “Social Media Marketing Taskforce“. In this group, the members include Lynn Zhang from the US’s Seattle Office and Roy Mustang from the UK’s London Office. Notice that both Lynn Zhang and Roy Mustang are from different departments, in different offices and separately located. For some business requirements to form task force like this, we can still create a group and assign both of them as members. The “Social Media Marketing Taskforce” group is created under the OU of US\Seattle Office. The below are the pictures of the users (more specifically INetOrgPerson) in different OUs and in their respective groups.

Here are some snap shots for your reference:

Figure 1: US – Seattle Office	Figure 2: UK – London Office
Figure 3: Social Media Marketing Taskforce Group Members	Figure 4: User Organization Properties

Windows Active Directory Authentication through Java JNDI

Ok, enough of stories and let’s get on to the core. In order to start authenticating against the Active Directory in your Java codes, we begin by defining the environment properties and getting the InitialDirContext class object initialized. This is shown in the codes sample below. The below codes will try to authenticate Adam Bristol, who is the Marketing Manager with the login name of “adambristol” and password “passwd1234” into the system:

Hashtable<String, String> env = new Hashtable<String, String>();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.PROVIDER_URL, "ldap://127.0.0.1:389");
 
// The value of Context.SECURITY_PRINCIPAL must be the logon username with the domain name
env.put(Context.SECURITY_PRINCIPAL, "adambristol@developerscrappad.com");
 
// The value of the Context.SECURITY_CREDENTIALS should be the user's password
env.put(Context.SECURITY_CREDENTIALS, "passwd1234");
 
DirContext ctx;
 
try {
    // Authenticate the logon user
    ctx = new InitialDirContext(env);
 
    /**
     * Once the above line was executed successfully, the user is said to be
     * authenticated and the InitialDirContext object will be created.
     */
 
} catch (NamingException ex) {
    // Authentication failed, just check on the exception and do something about it.
}

** Please don’t forget to change the Context.PROVIDER_URL value to the IP or hostname of your Active Directory server.

Notice that the value for Context.SECURITY_PRINCIPAL that was put into is “adambristol@developerscrappad.com“. Besides the logon username, we have to tail it with “@developerscrappad.com” which is the domain name. Please don’t forget to do this. In fact, Context.SECURITY_PRINCIPAL‘s value should be the value to match against the attribute userPrincipalName in the Active Directory tree, hence “adambristol@developerscrappad.com” should be the right value.

How To Know / Where To Find The Domain Name?

If you are the one who had created and initialized the Active Directory, you’ll definitely know the domain name because you are the one who defines it. But for folks who are navigating around a foreign system, you can always ask the Windows Server Administrator, or if you have the AD administrative privilege, just login to the server, click on Start => Administration => Active Directory Users and Computers, you should be able to find it at the very top level of the directory tree like the below:

Figure 5: Where To Find The Domain Name

How to Enable Application Features through Filtering OU, Department, Job Title and Groups

At times, the developing software application may not only require Active Directory authentication, but also to have certain features of the application to be made available for people in specific department, job title or even for a certain specific organizational unit. We’ll explore privilege checking or rather common known as access control one by one. From here onwards, you might need LDAP tools to gain access and to view the directory tree for a clearer picture.

How to Check If a Logon User Belongs to a Specific Organizational Unit

By using the LDAP browser from Eclipse as an example LDAP tree browsing tool, login into the Active Directory as “adambristol@developerscrappad.com“, scroll to the Adam Bristol branch through expending DC=developerscrappad,DC=com => OU=US => OU=Seattle Office => CN=Adam Bristol. As mentioned above, what identify Adam Bristol are both the sAMAccountName attribute and the userPrincipalName attribute. If you need something visual, just take a look at the below attached a picture where the important spots had been marked with red boxes.

Figure 6: LDAP Browser’s Output For User Adam Bristol

Once you have the information, the next thing is to put it in codes. The purpose of the below code sample is to check if OU=US => OU=Seattle Office under the domain of DC=developerscrappad,DC=com has such a person call Adam Bristol, identified by the person’s sAMAccountName (which is the logon username) “adambristol” and userPrincipalName adambristol@developerscrappad.com.

** Side Note: In fact, it will be sufficient and appropriate to only match the username with userPrincipalName as it is the preferred logon name for Windows 2000 and above. sAMAccountName is still being used but it is the logon name which used to support clients and servers from a previous version of Windows (such as Windows NT 4.0 and earlier, Windows 95, Windows 98, and LAN Manager). But here, we’ll use both as an example to illustrate some concepts.

Hashtable<String, String> env = new Hashtable<String, String>();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.SECURITY_PRINCIPAL, "adambristol@developerscrappad.com");
env.put(Context.SECURITY_CREDENTIALS, "passwd1234");
env.put(Context.PROVIDER_URL, "ldap://127.0.0.1:389");
DirContext ctx;
 
try {
    //Authenticate the logon user
    ctx = new InitialDirContext(env);
 
    //Start checking if the user is within the organization unit(s)
    String searchBase = "OU=Seattle Office,OU=US,DC=developerscrappad,DC=com";
    String searchFilter = "(&(objectClass=person)(sAMAccountName=adambristol)(userPrincipalName=adambristol@developerscrappad.com))";
    SearchControls sCtrl = new SearchControls();
    sCtrl.setSearchScope(SearchControls.ONELEVEL_SCOPE);
 
    NamingEnumeration answer = ctx.search(searchBase, searchFilter, sCtrl);
 
    boolean pass = false;
    if (answer.hasMoreElements()) {
        pass = true;
    }
 
    if (pass) {
        // The user belongs to the specified OU(s), do something...
    } else {
        // The user doesn't belong to the specified OU(s)
    }
} catch (NamingException ex) {
    //Do something with the exception...
}

Codes Explanation: Understanding searchBase
As you can see, what we are trying to achieve is to define a SearchControl object to be used for searching the tree with the DirContext object. In order to make SearchControl complete, we must first define the searchBase and the searchFilter.

In simple terms, the searchBase is the LDAP path on where the search should begin. Since Adam Bristol resides under DC=developerscrappad,DC=com => OU=US => OU => Seattle Office, the value for searchBase should be the reverse order (from further node of the tree to the root node), hence:

String searchBase = "OU=Seattle Office,OU=US,DC=developerscrappad,DC=com";

Codes Explanation: Understanding searchFilter
The searchFilter variable is where we input the LDAP search filter query. This query conforms to specific LDAP filter query syntax, you may find the syntax documented here for further understanding. For now, the query will be matching sAMAccoutName=adambristol and the userPrincipalName=adambristol@developerscrappad.com and we need to make sure the filter returns a person object with “objectClass=person” Hence:

String searchFilter = \
    "(&(objectClass=person)(sAMAccountName=adambristol)\
    (userPrincipalName=adambristol@developerscrappad.com))";

Once both the searchBase and the searchFilter variables are defined, the SearchControl object is where we put them to work. The ctx.search() method will generate results as an instance of NamingEnumeration. If it has of records to be iterated, it means, the user is part of the specified OU. Easy isn’t it?

How To Check If A Logon User Belongs To A Specific Department

A department qualifying process is slightly different. Instead of traversing through the Active Directory tree, it requires a further filter of the department attribute for a specific user.

Taking an example of checking if Roy Mustang belongs to the Systems Development department, just login through the LDAP tools of your and navigate to DC=developerscrappad,DC=com => OU=UK => OU=London Office => CN=Roy Mustang, you should be able to see the attribute call “department“. The value of the “department” attribute is what we need to check if Roy Mustang is part of the Systems Development department.

Figure 7: LDAP Browser’s Output For User Roy Mustang

As for the codes, please refer to the below:

Hashtable<String, String> env = new Hashtable<String, String>();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.PROVIDER_URL, "ldap://127.0.0.1:389");
env.put(Context.SECURITY_PRINCIPAL, "roymustang@developerscrappad.com");
env.put(Context.SECURITY_CREDENTIALS, "passwd1234");
 
DirContext ctx;
 
try {
    //Authenticate the logon user
    ctx = new InitialDirContext(env);
 
    // Perform the check
    String searchBase = "DC=developerscrappad,DC=com";
    String searchFilter = "(&(objectClass=person)(userPrincipalName=roymustang@developerscrappad.com)(department=Systems Development))";
    SearchControls sCtrl = new SearchControls();
    sCtrl.setSearchScope(SearchControls.SUBTREE_SCOPE);
    NamingEnumeration answer = ctx.search(searchBase, searchFilter, sCtrl);
 
    boolean pass = false;
    if (answer.hasMoreElements()) {
        pass = true;
    }
 
    if (pass) {
        // The user belongs to the specified department, do something...
    } else {
        // The user doesn't belong to the specified department
    }
 
} catch (NamingException ex) {
    //Do something with the exception...
}

Codes Explanation:
For the codes above, we don’t have to specify the OU string in the searchBase; but please make sure that the root domain string e.g. “DC=developerscrappad,DC=com” must be there. But the catch is to make sure the search scope of the SearchControl to be set to “SearchControls.SUBTREE_SCOPE“. This is to instruct the search to perform not only from the specified searchBase, but also to search in the entire sub-tree (branches) as well.

Since we are to filter if the specific user has the “department” attribute value of “Systems Development“, we’ll have to make sure that the searchFilter consists of the precise query. Hence:

String searchFilter = \
    "(&(objectClass=person)(userPrincipalName=roymustang@developerscrappad.com)\
    (department=Systems Development))";

How to Check & Qualify the Job Title of a Logon User

Some applications require the check of job title to see if the user is more or less superior to the others, thus allowing the user to gain access or limit on certain features in the application. Turning back to our dear marketing manager Adam Bristol and with the help of LDAP tools, the attribute that carries the job title for a specific user is “title” in the Active Directory tree.

Figure 8: LDAP Browser’s Output (Knowing “title”)

So, how can we filter the job title? Here are the codes to it:

Hashtable<String, String> env = new Hashtable<String, String>();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.PROVIDER_URL, "ldap://127.0.0.1:389");
env.put(Context.SECURITY_PRINCIPAL, "adambristol@developerscrappad.com");
env.put(Context.SECURITY_CREDENTIALS, "passwd1234");
 
DirContext ctx;
 
try {
    //Authenticate the logon user
    ctx = new InitialDirContext(env);
 
    // Check if the user has a job title of "Marketing Manager"
    String searchBase = "DC=developerscrappad,DC=com";
    String searchFilter = "(&(objectClass=person)(userPrincipalName=adambristol@developerscrappad.com)(title=Marketing Manager))";
    SearchControls sCtrl = new SearchControls();
    sCtrl.setSearchScope(SearchControls.SUBTREE_SCOPE);
 
    NamingEnumeration answer = ctx.search(searchBase, searchFilter, sCtrl);
 
    boolean pass = false;
    if (answer.hasMoreElements()) {
        pass = true;
    }
 
    if (pass) {
        // The user does carry the specified job title, do something...
    } else {
        // The user doesn't carry the specified job title
    }
} catch (NamingException ex) {
    //Do something with the exception...
}

Codes Explanation:
The codes are very much the same as how we check on the department in the previous example. The only change is to tweak the searchFilter string. Since we are matching the “title” attribute, we have to qualify all objectClass=person, the “userPrincipalName” and the “title” attribute values at the same time. Hence:

String searchFilter = \
    "(&(objectClass=person)(userPrincipalName=adambristol@developerscrappad.com)\
    (title=Marketing Manager))";

How To Check If A User Belongs To A Specific Group

Checking and filtering whether a user belongs to a group can be as straight forward as all the previous examples that we’ve gone through but when it comes to group name matching with wildcard or partial match, it may not be as straight forward as it seems. Referring to user Lynn Zhang, she’s part of the “Social Media Marketing Taskforce” group. Going back to the LDAP Browser, in order to check if a user belongs to a certain specific group, you’ll need to look at the “memberOf” attribute shown in the below picture. Please take note that if the user belongs to multiple groups, there will be multiple attributes of “memberOf” with different values. The value of the “memberOf” attribute is the full qualified distinguished name of the group.

Figure 9: LDAP Browser’s Output (Knowing “memberOf”)

Group Name Exact Match

In order to check if a user belongs to a group, the exact full qualified path of the group (the same value in “memberOf” attribute) is required. The sample codes are as below:

Hashtable<String, String> env = new Hashtable<String, String>();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.PROVIDER_URL, "ldap://127.0.0.1:389");
env.put(Context.SECURITY_PRINCIPAL, "lynnzhang@developerscrappad.com");
env.put(Context.SECURITY_CREDENTIALS, "passwd1234");
 
DirContext ctx;
 
try {
    //Authenticate the logon user
    ctx = new InitialDirContext(env);
    String searchBase = "DC=developerscrappad,DC=com";
 
    // Perform an exact group match with the "memberOf" attribute.
    StringBuilder searchFilter = new StringBuilder("(&");
    searchFilter.append("(objectClass=person)");
    searchFilter.append("(userPrincipalName=lynnzhang@developerscrappad.com)");
    searchFilter.append("(memberOf=CN=Social Media Marketing Taskforce,OU=Seattle Office,OU=US,DC=developerscrappad,DC=com)");
    searchFilter.append(")");
 
    SearchControls sCtrl = new SearchControls();
    sCtrl.setSearchScope(SearchControls.SUBTREE_SCOPE);
 
    NamingEnumeration answer = ctx.search(searchBase, searchFilter.toString(), sCtrl);
    boolean pass = false;
 
    if (answer.hasMoreElements()) {
        pass = true;
    }
 
    if (pass) {
        // The user belongs to the group. Do something...
    } else {
        // The user doesn't belong to the group.
    }
} catch (NamingException ex) {
    //Do something with the exception...
}

Group Name Partial Match

At time, searching through the Active Directory tree with exact match like the above will be painful especially if you are dealing with a very large directory and the matching string for “memberOf” will be tremendously long. Of course it will give the absolute result right on the dot, but what if the Administrator decides to move the group from where it was? This will cause the whole entire application to break. We can still partially match the group name in the “memberOf” attribute value with the codes below:

Hashtable<String, String> env = new Hashtable<String, String>();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.PROVIDER_URL, "ldap://127.0.0.1:389");
env.put(Context.SECURITY_PRINCIPAL, "lynnzhang@developerscrappad.com");
env.put(Context.SECURITY_CREDENTIALS, "passwd1234");
 
DirContext ctx;
 
try {
    //Authenticate the logon user
    ctx = new InitialDirContext(env);
 
    // Prepare the search criteria for group name matching
    String searchBase = "DC=developerscrappad,DC=com";
 
    StringBuilder searchFilter = new StringBuilder("(&");
    searchFilter.append("(objectClass=person)");
    searchFilter.append("(userPrincipalName=lynnzhang@developerscrappad.com)");
    searchFilter.append(")");
 
    String returnAttrs[] = {"memberOf"};
    SearchControls sCtrl = new SearchControls();
    sCtrl.setSearchScope(SearchControls.SUBTREE_SCOPE);
    sCtrl.setReturningAttributes(returnAttrs);
 
    NamingEnumeration<SearchResult> answer = ctx.search(searchBase, searchFilter.toString(), sCtrl);
    boolean pass = false;
 
    // Define the match string
    String match = "Social Media Marketing Taskforce";
 
    // Loop through the results and check every single value in attribute "memberOf"
    while (answer.hasMoreElements()) {
        SearchResult sr = answer.next();
        String memberOfAttrValue = sr.getAttributes().get("memberOf").toString();
 
        if (memberOfAttrValue.contains(match)) {
            pass = true;
            break;
        }
    }
 
    if (pass) {
        // The user belongs to the group (no exact group path). Do something...
    } else {
        // The user doesn't belong to the group.
    }
 
} catch (NamingException ex) {
    //Do something with the exception...
}

Codes Explanation:
Here, the searchFilter string is pretty simple by only matching the “objectClass” as “person” and “userPrincipalName” with the full logon username. The returnAttrs string array is introduced to be used by the SearchControl object so that when we retrieve the attributes of the returned records, only the “memberOf” attribute is returned.

As it progress and returns the instance of NamingEnumeration, we’ll iterate it and retrieve each item as an instance of SearchResult. From there, we’ll just get the attribute value and call the java.lang.String.contains() method to match the Group Name. Iteration through the NamingEnumeration object is required as sometimes, one user may belong to multiple groups. So, taking each “memberOf” attribute to compare is necessary.

This way is truly not very reliable and is definitely not a very efficient way, but it does get the job done when circumstances arise.

Why Can’t We Use Wildcard “*” On “memberOf”?

It is tempting to have searchFilter with something like:

(&(objectClass=person)(userPrincipalName=someone@domain)(memberOf=CN=Some Group Name*))

It is irritating, if not, frustrating at first. But by knowing this fact, it allows you to pre-plan your development approach before you hit a bumper like this.

Summary

We’ve come to the end of the article and I hope it truly gave you a good kick start your Java/JNDI to Active Directory Server authentication, searching and validating of OU, groups and other attributes as a means to aid in information search or access control of your software application. Just make sure you keep your LDAP tools handy and always remember that wildcard doesn’t work on attributes which are type Distinguished Name. Pre-plan your development approach and you should do well.

Wishing all of you success in coding and thank you for reading.

Related Articles:

• Quick Note: Unable To Perform LDAP Wildcard “*” Search On Windows Active Directory
• Java LDAP/JNDI: 2 Ways Of Decoding And Using The objectGUID From Windows Active Directory

Preparing The Test Database and Test Table

The first task that we need to do is to setup a database and the relevant test table to perform the test procedure. Here, you may use the Management Server mysqlmngserv’s (192.168.2.50) terminal any other terminal to perform the commands, as long as there is a MySQL client on the machine.

The database that we’ll create is call NDB_TEST and the table that will be created is call NDB_TEST_TABLE. And we will create these tables with the “world_dba” user created in the MySQL database previously. Let’s get started by connecting to the terminal of the Management Server mysqlmngserv (192.168.2.50) as the “mysql” user:

1. Change the working directory to /opt/mysql/mysql/bin by typing “cd /opt/mysql/mysql/bin“
2. To create the database, let’s connect to mysqlserv1 (192.168.2.51)’s SQL Node by typing “./mysql -u world_dba -pworldpasswd -h 192.168.2.51“.
3. Once you have log into the mysql> prompt, type “CREATE DATABASE NDB_TEST;“.
4. Instruct MySQL to use the newly created database by typing “USE NDB_TEST;“.
5. Now, create the table with the below script on the mysql> prompt:
   

   CREATE TABLE NDB_TEST_TABLE
   (
   	PK BIGINT NOT NULL AUTO_INCREMENT,
   	ACTIVITY_TS TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
   	ACTIVITY_LOG TEXT NOT NULL,
   	PRIMARY KEY(PK)
   ) Engine=NDBCLUSTER;

The NDB_TEST_TABLE is a simple table containing with column ACTIVITY_LOG as a column for message that we’ll enter and the ACTIVITY_TS as the timestamp field when a record is inserted. It will be populated with the timestamp at the time of insertion.

Test 1: Test When All Servers Are Up

Perform this as the “mysql” OS user on the Management Server mysqlmngserv (192.168.2.50):

1. Change the working directory to /opt/mysql/mysql/bin “cd /opt/mysql/mysql/bin“.
2. Just do a brief check on all the servers’ statuses by typing “./ndb_mgm -e show“, you shoule be getting the output like below:
   

   Connected to Management Server at: localhost:1186
   Cluster Configuration
   ---------------------
   [ndbd(NDB)]     4 node(s)
   id=11   @192.168.2.53  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0, Master)
   id=12   @192.168.2.54  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0)
   id=13   @192.168.2.55  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)
   id=14   @192.168.2.56  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)
   
   [ndb_mgmd(MGM)] 1 node(s)
   id=1    @192.168.2.50  (mysql-5.5.27 ndb-7.2.8)
   
   [mysqld(API)]   2 node(s)
   id=31   @192.168.2.51  (mysql-5.5.27 ndb-7.2.8)
   id=32   @192.168.2.52  (mysql-5.5.27 ndb-7.2.8)
   

   With this we are sure that all servers within the cluster are now up and running.

3. While still at the terminal’s command prompt, use the MySQL client to login to the first SQL Node mysqlserv1 (192.168.2.51) by typing “./mysql -u world_dba -pworldpasswd -h 192.168.2.51“.
4. At the mysql> prompt, perform the below command:
   

   USE NDB_TEST;
   INSERT INTO NDB_TEST_TABLE (ACTIVITY_LOG) VALUES ('Inserted when all servers are up!');
   SELECT * FROM NDB_TEST_TABLE ORDER BY ACTIVITY_TS;

   You should be able to see the below output:
   

   +----+---------------------+-----------------------------------+
   | PK | ACTIVITY_TS         | ACTIVITY_LOG                      |
   +----+---------------------+-----------------------------------+
   |  1 | 2012-09-19 13:11:26 | Inserted when all servers are up! |
   +----+---------------------+-----------------------------------+
   

With this, the first test had passed.

Test 2: Test When mysqlserv1 Is Offline And mysqlserv2 Is Online

Perform this as the “mysql” OS user on the Management Server mysqlmngserv (192.168.2.50):

1. Change the working directory to /opt/mysql/mysql/bin “cd /opt/mysql/mysql/bin“.
2. In the terminal’s command prompt, type the following to shutdown SQL Node 1 mysqlserv1 (192.168.2.51) remotely: “./mysqladmin -u world_dba -pworldpasswd -h 192.168.2.51 shutdown“.
3. To make sure that SQL Node 1 is offline, just check through “./ndb_mgm -e show” on the terminal of the Manage Server and you should be able to see something like the below:
   

   Connected to Management Server at: localhost:1186
   Cluster Configuration
   ---------------------
   [ndbd(NDB)]     4 node(s)
   id=11   @192.168.2.53  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0, Master)
   id=12   @192.168.2.54  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0)
   id=13   @192.168.2.55  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)
   id=14   @192.168.2.56  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)
   
   [ndb_mgmd(MGM)] 1 node(s)
   id=1    @192.168.2.50  (mysql-5.5.27 ndb-7.2.8)
   
   [mysqld(API)]   2 node(s)
   id=31 (not connected, accepting connect from 192.168.2.51)
   id=32   @192.168.2.52  (mysql-5.5.27 ndb-7.2.8)
   

4. While still at the terminal command prompt, use the MySQL client to connect to SQL Node 2 mysqlserv2 (192.168.2.52) by typing “./mysql -u world_dba -pworldpasswd -h 192.168.2.52“.
5. Once you have log into the mysql> prompt, enter the following command:
   

   USE NDB_TEST;
   INSERT INTO NDB_TEST_TABLE (ACTIVITY_LOG) VALUES ('Inserted when mysqlserv1 is down');
   SELECT * FROM NDB_TEST_TABLE ORDER BY ACTIVITY_TS;

   You should be able to see the following output:
   

   +----+---------------------+-----------------------------------+
   | PK | ACTIVITY_TS         | ACTIVITY_LOG                      |
   +----+---------------------+-----------------------------------+
   |  1 | 2012-09-19 13:11:26 | Inserted when all servers are up! |
   |  2 | 2012-09-19 13:15:07 | Inserted when mysqlserv1 is down  |
   +----+---------------------+-----------------------------------+
   

Test 3: Test When mysqlserv1 Is Online And mysqlserv2 Is Offline

In this test, we’ll activate SQL Node 1 and stop the SQL Node 2, insert a record through SQL Node 2 and see if the data is consistent.

First, we have to get SQL Node 1 mysqlserv1 (192.168.2.51) up and running again, then shutdown SQL Node 2 mysqlserv2 (192.168.2.52). Follow the below instruction:

Log into the terminal of mysqlser1 (192.168.2.52) as the “mysql” user:

1. Change the working directory to /opt/mysql/mysql/bin “cd /opt/mysql/mysql/bin“.
2. Type “./mysqld –defaults-file=/opt/mysql/mysql/current-running-config-files/mysql.mysqlserv1.cnf &” to bring back mysqlserv1
3. Then in the same terminal and working directory, type “./mysqladmin -u world_dba -pworldpasswd -h 192.168.2.52 shutdown” to shutdown the mysqlserv2 SQL Node.

For status checking, just switch the terminal back to Management Server and perform a “ndb_mgm -e show” command, you should be able to see the below output:

Connected to Management Server at: localhost:1186
Cluster Configuration
---------------------
[ndbd(NDB)]     4 node(s)
id=11   @192.168.2.53  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0, Master)
id=12   @192.168.2.54  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0)
id=13   @192.168.2.55  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)
id=14   @192.168.2.56  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)

[ndb_mgmd(MGM)] 1 node(s)
id=1    @192.168.2.50  (mysql-5.5.27 ndb-7.2.8)

[mysqld(API)]   2 node(s)
id=31   @192.168.2.51  (mysql-5.5.27 ndb-7.2.8)
id=32 (not connected, accepting connect from 192.168.2.52)

In the same terminal, we have to connect to mysqlserv1 through the MySQL client and perform the below:

1. In the working directory /opt/mysql/mysql/bin, connect to mysqlserv1 by typing “./mysql -u world_dba -pworldpasswd -h 192.168.2.51“.
2. When you reach the mysql> prompt, perform the below command:
   

   USE NDB_TEST;
   INSERT INTO NDB_TEST_TABLE (ACTIVITY_LOG) VALUES ('Inserted when mysqlserv2 is down');
   SELECT * FROM NDB_TEST_TABLE ORDER BY ACTIVITY_TS;

   
   You should be able to see the below output:
   

   +----+---------------------+-----------------------------------+
   | PK | ACTIVITY_TS         | ACTIVITY_LOG                      |
   +----+---------------------+-----------------------------------+
   |  1 | 2012-09-19 13:11:26 | Inserted when all servers are up! |
   |  2 | 2012-09-19 13:15:07 | Inserted when mysqlserv1 is down  |
   |  3 | 2012-09-19 13:26:03 | Inserted when mysqlserv2 is down  |
   +----+---------------------+-----------------------------------+
   

Once you’ve completed Test 3, we are quite sure that both the SQL Nodes mysqlserv1 and mysqlserv2 are indeed connected to the specify data nodes in the configuration and the Management Server is working in coordinating the data synchronization.

So in future, any external application which are to connect to the database could switch between mysqlserv1 or mysqlserv2 in a load-balanced round robin way.

Test 4: Test When mysqldn1 – NodeId 11 (192.168.2.53) And mysqldn3 – NodeId 13 (192.168.2.55) Is Offline

Things will get interesting from here on. Instead of taking turns to shut down the SQL Nodes, in this test, we’ll shutdown the two of the Data Nodes to see if the data truly syncs and if data node fail-over actually works. Just follow the below (just make sure all SQL Nodes are back and alive before doing this).

Log into the Management Server mysqlmngserv (192.168.2.50) as the “mysql” user and perform the following:

1. Change the working directory to /opt/mysql/mysql/bin “cd /opt/mysql/mysql/bin“.
2. We’ll perform the data node shutdown through the management console. Type “./ndb_mgm” in the command prompt.
3. Through the ndb_mgm&gt: prompt, type “show” to show the list of data nodes.
4. To stop Data Node 1 – mysqldn1 (192.168.2.53), NodeId: 11, just type “11 stop“. Wait for the data node to stop with response like:
   

   ndb_mgm> 11 stop
   Node 11: Node shutdown initiated
   Node 11 has shutdown.
   

5. Then, to stop Data Node 3 – mysqldn3 (192.168.2.55), NodeId: 13, just type “13 stop“. Wait for the data node to stop with response like:
   

   ndb_mgm> 13 stop
   Node 13: Node shutdown initiated
   Node 13 has shutdown.
   

6. Type “show” again, and you should see the below:
   

   Connected to Management Server at: localhost:1186
   Cluster Configuration
   ---------------------
   [ndbd(NDB)]     4 node(s)
   id=11 (not connected, accepting connect from 192.168.2.53)
   id=12   @192.168.2.54  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0, Master)
   id=13 (not connected, accepting connect from 192.168.2.55)
   id=14   @192.168.2.56  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)
   
   [ndb_mgmd(MGM)] 1 node(s)
   id=1    @192.168.2.50  (mysql-5.5.27 ndb-7.2.8)
   
   [mysqld(API)]   2 node(s)
   id=31   @192.168.2.51  (mysql-5.5.27 ndb-7.2.8)
   id=32   @192.168.2.52  (mysql-5.5.27 ndb-7.2.8)
   

7. So now, when both NodeId 11 and NodeId 13 are down, type “exit” on the ndb_mgm> prompt to exit the console and connect the MySQL client to mysqlserv1 192.168.2.51 by typing “./mysql -u world_dba -pworldpasswd -h 192.168.2.51“.
8. In the mysql&gt: prompt, just enter the below commands:
   

   USE NDB_TEST;
   INSERT INTO NDB_TEST_TABLE (ACTIVITY_LOG) VALUES ('Inserted when Data Node 1 (NodeId 11) and Data Node 3 (NodeId 13) is down');
   SELECT * FROM NDB_TEST_TABLE ORDER BY ACTIVITY_TS;

   This will result the following output:
   

   +----+---------------------+---------------------------------------------------------------------------+
   | PK | ACTIVITY_TS         | ACTIVITY_LOG                                                              |
   +----+---------------------+---------------------------------------------------------------------------+
   |  1 | 2012-09-19 13:11:26 | Inserted when all servers are up!                                         |
   |  2 | 2012-09-19 13:15:07 | Inserted when mysqlserv1 is down                                          |
   |  3 | 2012-09-19 13:26:03 | Inserted when mysqlserv2 is down                                          |
   |  4 | 2012-09-19 13:32:44 | Inserted when Data Node 1 (NodeId 11) and Data Node 3 (NodeId 13) is down |
   +----+---------------------+---------------------------------------------------------------------------+
   

If you see the above output, that shows the cluster could still perform transaction on the database even without two functioning data nodes.

Test 5: Test When mysqldn2 – NodeId 12 (192.168.2.54) And mysqldn4 – NodeId 14 (192.168.2.56) Is Offline

Before we give this test a try, just make sure that the previously shutdown data nodes are back alive again. You can do this by:

1. Log into mysqldn1 (192.168.2.53) through the terminal as “mysql” user.
2. Change the working directory to /opt/mysql/mysql/bin by typing “cd /opt/mysql/mysql/bin“.
3. In the command prompt, type “./ndbd -c 192.168.2.50:1186” to connect the data node to the Management Server at 192.168.2.50. Notice that now, this command doesn’t require the flag “–initial“. Do check on the MySQL documentation for the purpose of initial flag. Now as we start the data node again for the next time, we don’t need that. But if you are starting the data node for the first time, please have the “–initial” flag.
4. Wait for it to be connected, then repeat step 1 to 3 with mysqldn3 at 192.168.2.55

So, once both mysqldn1 NodeId 11 and mysqldn3 NodeId 13 is up and running again, its time to shutdown mysqldn2 NodeId 12 and mysqldn4 NodeId 14. Just perform this with the same procedure as mentioned in Test 4, access the Management Server’s ndb_mgm> console and type “12 stop” and “14 stop“. When both the data nodes had stopped, check the status again with “./ndb_mgm -e show” and you should see:

Cluster Configuration
---------------------
[ndbd(NDB)]     4 node(s)
id=11   @192.168.2.53  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0, Master)
id=12 (not connected, accepting connect from 192.168.2.54)
id=13   @192.168.2.55  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)
id=14 (not connected, accepting connect from 192.168.2.56)

[ndb_mgmd(MGM)] 1 node(s)
id=1    @192.168.2.50  (mysql-5.5.27 ndb-7.2.8)

[mysqld(API)]   2 node(s)
id=31   @192.168.2.51  (mysql-5.5.27 ndb-7.2.8)
id=32   @192.168.2.52  (mysql-5.5.27 ndb-7.2.8)

Once NodeId 12 and NodeId 14 had been shutdown, perform the following:

1. Type “exit” on the ndb_mgm> prompt to exit the console and connect the MySQL client to mysqlserv1 192.168.2.51 by typing “./mysql -u world_dba -pworldpasswd -h 192.168.2.51“.
2. In the mysql&gt: prompt, just enter the below commands:
   

   USE NDB_TEST;
   INSERT INTO NDB_TEST_TABLE (ACTIVITY_LOG) VALUES ('Inserted when Data Node 2 (NodeId 12) and Data Node 4 (NodeId 14) is down');
   SELECT * FROM NDB_TEST_TABLE ORDER BY ACTIVITY_TS;

   This will result the following output:
   

   +----+---------------------+---------------------------------------------------------------------------+
   | PK | ACTIVITY_TS         | ACTIVITY_LOG                                                              |
   +----+---------------------+---------------------------------------------------------------------------+
   |  1 | 2012-09-19 13:11:26 | Inserted when all servers are up!                                         |
   |  2 | 2012-09-19 13:15:07 | Inserted when mysqlserv1 is down                                          |
   |  3 | 2012-09-19 13:26:03 | Inserted when mysqlserv2 is down                                          |
   |  4 | 2012-09-19 13:32:44 | Inserted when Data Node 1 (NodeId 11) and Data Node 3 (NodeId 13) is down |
   |  5 | 2012-09-19 13:38:34 | Inserted when Data Node 2 (NodeId 12) and Data Node 4 (NodeId 14) is down |
   +----+---------------------+---------------------------------------------------------------------------+
   

Once you’ve gotten the above test result, it is quite safe to say that the cluster is working well as it is intended to be.

Final Test: Test When All Servers and Data Nodes Are Up Again

Just to wrap things up, let’s put back every shutdown data nodes to live and restore the cluster to its normal working order. In the previous test, we’ve shutdown NodeId 12 and NodeId 14, so just switch to mysqldn2 (192.168.2.54)’s terminal and reconnect the data node to the Manage Server again with “ndbd -c 192.168.2.50:1186“, do the same to mysqldn4 (192.168.2.56). Verify with “ndb_mgm -e show” command on the Management Server and you should get back the below result:

Connected to Management Server at: localhost:1186
Cluster Configuration
---------------------
[ndbd(NDB)]     4 node(s)
id=11   @192.168.2.53  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0, Master)
id=12   @192.168.2.54  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0)
id=13   @192.168.2.55  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)
id=14   @192.168.2.56  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)

[ndb_mgmd(MGM)] 1 node(s)
id=1    @192.168.2.50  (mysql-5.5.27 ndb-7.2.8)

[mysqld(API)]   2 node(s)
id=31   @192.168.2.51  (mysql-5.5.27 ndb-7.2.8)
id=32   @192.168.2.52  (mysql-5.5.27 ndb-7.2.8)

Perform the final test below with the “mysql” user on the Management Server:

1. Assuming that you are at the working path of “/opt/mysql/mysql/bin“, connect the MySQL client to mysqlserv1 (192.168.2.51) by typing “./mysql -u world_dba -pworldpasswd -h 192.168.2.51“.
2. When you reach the mysql> prompt, type the following command:
   

   USE NDB_TEST;
   INSERT INTO NDB_TEST_TABLE (ACTIVITY_LOG) VALUES ('Inserted all servers are up and living again. Test Completed!');
   SELECT * FROM NDB_TEST_TABLE ORDER BY ACTIVITY_TS;

3. You should be able to see the below output:
   

   +----+---------------------+---------------------------------------------------------------------------+
   | PK | ACTIVITY_TS         | ACTIVITY_LOG                                                              |
   +----+---------------------+---------------------------------------------------------------------------+
   |  1 | 2012-09-19 13:11:26 | Inserted when all servers are up!                                         |
   |  2 | 2012-09-19 13:15:07 | Inserted when mysqlserv1 is down                                          |
   |  3 | 2012-09-19 13:26:03 | Inserted when mysqlserv2 is down                                          |
   |  4 | 2012-09-19 13:32:44 | Inserted when Data Node 1 (NodeId 11) and Data Node 3 (NodeId 13) is down |
   |  5 | 2012-09-19 13:38:34 | Inserted when Data Node 2 (NodeId 12) and Data Node 4 (NodeId 14) is down |
   |  6 | 2012-09-19 13:41:58 | Inserted all servers are up and living again. Test Completed!             |
   +----+---------------------+---------------------------------------------------------------------------+
   

With this, we can conclude that the cluster, at least for the data persisting aspect is running fine.

Summary

We have now come to the end of this three part series on MySQL Cluster NDB 7.2 on Solaris 10. although it is just a mini series on a relatively simple cluster configuration but hopefully, you are able to get the idea of how to successfully build and deploy a MySQL Cluster environment on the Solaris 10 OS, at least knowing the minimal configuration requirement for the .cnf and config.ini files, the data directories, using the Management Server for certain cluster controls, enabling of synchronized distributed user management and shared privileges and finally, brief testing of the cluster to see if it is truly functioning as it is intended to be. The journey doesn’t end here though as there are many other aspects that the learning curve consist of including cluster replication, backups, restores, optimization, etc. which is well worth your time to understand if you are serious about maintaining the cluster(s).

Well, wishing you many success in your future MySQL cluster deployment and hope you’ve enjoyed reading our articles.

Thank you.

Related Articles

• MySQL Cluster NDB 7.2 on Solaris 10 Part 2 – Starting, Distributed Synchronized Users Management And Stopping The Cluster
• MySQL Cluster NDB 7.2 on Solaris 10 Part 1 – How To Install, Setup and Configure
• Installing MySQL 5.0 on Solaris 10
• Installing MySQL 5.5 on Solaris 10
• How To Boot MySQL 5.5 On Solaris 10 During System Startup

Gentlemen, Start Your Engines!

This is the moment of truth, after all the laborious efforts in installing and configuring the servers, it is time to put the cluster in action. But before you do that, there is a sequence to which server to start. The rule of thumb is always to start the management server, follow by the data nodes, then the SQL Nodes as the last to be started.

Starting the Management Server

Perform this as the “mysql” user on the Management Server mysqlmngserv (192.168.2.50):

1. Log into the terminal and switch to the user “mysql” by typing “su mysql“.
2. Change the working directory to /opt/mysql/mysql/bin by typing “cd /opt/mysql/mysql/bin“.
3. Start the Management Server by typing: “./ndb_mgmd -f /opt/mysql/mysql/current-running-config-files/config.ini –initial“.
4. You should be able to see the output like:
   

   ...
   # ./ndb_mgmd -f /opt/mysql/mysql/current-running-config-files/config.ini --initial
   MySQL Cluster Management Server mysql-5-5-27 ndb-7.2.8
   # 
   

   
   It will return to the prompt if is was started successfully.

5. Next, check the status of all the servers involve in the cluster by typing “./ndb_mgm -e show“, you should get something like the below:
   

   $ ./ndb_mgm -e show
   Connected to Management Server at: localhost:1186
   Cluster Configuration
   ---------------------
   [ndbd(NDB)]     4 node(s)
   id=11 (not connected, accepting connect from 192.168.2.53)
   id=12 (not connected, accepting connect from 192.168.2.54)
   id=13 (not connected, accepting connect from 192.168.2.55)
   id=14 (not connected, accepting connect from 192.168.2.56)
   
   [ndb_mgmd(MGM)] 1 node(s)
   id=1    @192.168.2.50  (mysql-5.5.27 ndb-7.2.8)
   
   [mysqld(API)]   2 node(s)
   id=31 (not connected, accepting connect from 192.168.2.51)
   id=32 (not connected, accepting connect from 192.168.2.52)
   

As you can see from the terminal, the management server was successfully started; leaving the rest of the data nodes unconnected and of course the SQL Nodes are not running now.

Starting and Connecting The Data Nodes

The next step to do after starting the Management Server is to start and connect the data nodes. To do this just follow the below:

Please perform this one by one of ONLY the data node servers, from mysqldn1 (192.168.2.53) to mysqldn4 (192.168.2.56). You may first start with mysqldn1 (192.168.2.53). Please perform the below as the “mysql” user:

1. Log into the shell and switch to the user “mysql” by typing “su mysql“.
2. Change the working directory to /opt/mysql/mysql/bin by typing “cd /opt/mysql/mysql/bin“.
3. Connect the data nodes to the management server by typing “./ndbd –initial -c 192.168.2.50:1186“. The 192.168.2.50 is the IP of the Management Server (mnysqlmngserv) and the 1186 is actually the default port for the connection. This command actually starts and connects the data node to the management server both at the same time.
4. Switch back to the terminal of the Management Server (mysqlmngserv), change the working directory to /opt/mysql/mysql/bin and check the status again by typing “./ndb_mgm -e show“.
5. You would be getting the below output:
   

   $ ./ndb_mgm -e show
   Connected to Management Server at: localhost:1186
   Cluster Configuration
   ---------------------
   [ndbd(NDB)]     4 node(s)
   id=11   @192.168.2.53  (mysql-5.5.27 ndb-7.2.8, starting, Nodegroup: 0)
   id=12 (not connected, accepting connect from 192.168.2.54)
   id=13 (not connected, accepting connect from 192.168.2.55)
   id=14 (not connected, accepting connect from 192.168.2.56)
   
   [ndb_mgmd(MGM)] 1 node(s)
   id=1    @192.168.2.50  (mysql-5.5.27 ndb-7.2.8)
   
   [mysqld(API)]   2 node(s)
   id=31 (not connected, accepting connect from 192.168.2.51)
   id=32 (not connected, accepting connect from 192.168.2.52)
   

   
   The connecting data node(s) will have the status like “…mysql-5.5.27 ndb-7.2.8, starting, …”. Notice that there is a word “starting” in the status. Just be mindful that it will take sometime for the data node to get started.
6. Never mind about waiting. Just move on and repeat step 1 to 4 for mysqldn2 (192.168.2.54), mysqldn3 (192.168.2.55) and mysqldn4 (192.168.2.56) and you will eventually get the following output when you check the Management Server’s status with “ndb_mgm -e show“.
   

   Connected to Management Server at: localhost:1186
   Cluster Configuration
   ---------------------
   [ndbd(NDB)]     4 node(s)
   id=11   @192.168.2.53  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0, Master)
   id=12   @192.168.2.54  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0)
   id=13   @192.168.2.55  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)
   id=14   @192.168.2.56  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)
   
   [ndb_mgmd(MGM)] 1 node(s)
   id=1    @192.168.2.50  (mysql-5.5.27 ndb-7.2.8)
   
   [mysqld(API)]   2 node(s)
   id=31 (not connected, accepting connect from 192.168.2.51)
   id=32 (not connected, accepting connect from 192.168.2.52)
   

Starting the MySQL Server (SQL Nodes)

Now, for the final part of the cluster, follow the below instructions to start both of the SQL Nodes. Just perform this as the “mysql” user for ONLY both the mysqlserv1 (192.168.2.51) and mysqlserv2 (192.168.2.52). You may first do this on mysqlserv1 (192.168.2.51):

1. Log into the terminal and switch to the “mysql” user by typing “su mysql“
2. Change the working directory to /opt/mysql/mysq/bin by typing “cd /opt/mysql/mysql/bin“.
3. Start the MySQL server by typing “./mysqld –defaults-file=/opt/mysql/mysql/current-running-config-files/mysql.mysqlserv1.cnf &“. The –defaults-file flag will tell the SQL node to read the specific .cnf file from the directory current-running-config-files. The is the time when the mysql.mysqlserv1.cnf file created in Part 1 of the tutorial is put to use.
4. To check the status, you may always switch back to the Management Server mysqlmngserv (192.168.2.50) to see the status with the command “ndb_mgm -e show“. You should be getting an output like below:
   

   Connected to Management Server at: localhost:1186
   Cluster Configuration
   ---------------------
   [ndbd(NDB)]     4 node(s)
   id=11   @192.168.2.53  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0, Master)
   id=12   @192.168.2.54  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0)
   id=13   @192.168.2.55  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)
   id=14   @192.168.2.56  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)
   
   [ndb_mgmd(MGM)] 1 node(s)
   id=1    @192.168.2.50  (mysql-5.5.27 ndb-7.2.8)
   
   [mysqld(API)]   2 node(s)
   id=31   @192.168.2.51  (mysql-5.5.27 ndb-7.2.8)
   id=32 (not connected, accepting connect from 192.168.2.52)
   

5. For the next SQL Node mysqlserv2 (192.168.2.52), just switch to the server’s terminal repeat step 1 to 4. The command to start mysqlserv2 is “./mysqld –defaults-file=/opt/mysql/mysql/current-running-config-files/mysql.mysqlserv2.cnf &“. Just make sure you get the value for the –defaults-file parameter correct.

Finally, to see if all servers have started correctly, please switch back to the Management Server mysqlmngserv (192.168.2.50) and check with the command “ndb_mgm -e show“, you should be able to see the below output:

Connected to Management Server at: localhost:1186
Cluster Configuration
---------------------
[ndbd(NDB)]     4 node(s)
id=11   @192.168.2.53  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0, Master)
id=12   @192.168.2.54  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 0)
id=13   @192.168.2.55  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)
id=14   @192.168.2.56  (mysql-5.5.27 ndb-7.2.8, Nodegroup: 1)

[ndb_mgmd(MGM)] 1 node(s)
id=1    @192.168.2.50  (mysql-5.5.27 ndb-7.2.8)

[mysqld(API)]   2 node(s)
id=31   @192.168.2.51  (mysql-5.5.27 ndb-7.2.8)
id=32   @192.168.2.52  (mysql-5.5.27 ndb-7.2.8)

Enabling Distributed Synchronized User Management On MySQL Cluster NDB

Before you go ahead connecting and testing the cluster, we would like to bring to your attention that whatever user(s) that you had or are about to create on one MySQL server is NOT portable across the cluster by default. But there is a solution to it and this section will guide you in enabling synchronization of users across servers within the cluster. Let’s be patient and go through the instruction below, as it is well worth your effort.

Please perform this as the “mysql” user on the first SQL Node mysqlserv1 (192.168.2.51):

1. When you’ve log into the terminal, just change the directory to /opt/mysql/mysql/share by tying “cd /opt/mysql/mysql/share“.
2. If you list the directory with “ls” command, you should be able to see a file named “ndb_dist_priv.sql“. This script is to enable the cluster to create tables of engine NDB type for the storage of users’ info across all servers in the cluster.
3. To run the ndb_dist_priv.sql file, change the directory to /opt/mysql/mysql/bin with “cd /opt/mysql/mysql/bin” and type “./mysql -u root < ../share/ndb_dist_priv.sql“. This will load a couple of stored procedures into the database, which is to be used to perform the synchronization of users.
4. Next, you have to connect to the SQL node by typing “mysql -u root” and when it comes to the mysql> prompt, just type: “CALL mysql.mysql_cluster_move_privileges();“
5. While still at the mysql> prompt, just check on the conversion status by keying in a query “SELECT CONCAT(‘Conversion ‘, IF(mysql.mysql_cluster_privileges_are_distributed(), ‘succeeded’, ‘failed’), ‘.’) AS Result;” you should be getting an output like:
   

   +-----------------------+
   | Result                |
   +-----------------------+
   | Conversion succeeded. |
   +-----------------------+
   1 row in set (0.11 sec)
   

6. Please, you MUST repeat step 1 to 5 for mysqlserv2 (192.168.2.52). DO NOT MISS THIS STEP! And if we have any additional SQL Nodes to be added into the cluster in future, perform step 1 to 5 as well.

Once you’ve done the above, any user that you create in future will automatically be available throughout all the registered SQL Nodes. You may do the below to create a user “world_dba” with the password “worldpasswd“. We’ll be using world_dba to do our dirty works instead of the root user. Just connect to the database with “mysql -u root” on any of the SQL Nodes (either mysqlserv1 192.168.2.51 or mysqlserv2 192.168.2.52) and do the following on the mysql> prompt:

CREATE USER 'world_dba'@'localhost' IDENTIFIED BY 'worldpasswd';
CREATE USER 'world_dba'@'%' IDENTIFIED BY 'worldpasswd';
GRANT ALL PRIVILEGES ON *.* TO 'world_dba'@'localhost' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO 'world_dba'@'%' WITH GRANT OPTION;

Stopping The Cluster Gracefully

To stop the server process, most people will search for the mysql process with “ps -ef | grep mysql” and send the command “kill -p <proc no.>” with the “mysql” or the “root” user, but that’s not very graceful. In order to stop the servers with the proper stop command, just follow the below instruction.

How To Stop The MySQL Server (SQL Nodes)

To gracefully stop the SQL Nodes, just log into the terminal of the Management Server as the “mysql” user:

1. Change the working directory to “/opt/mysql/mysql/bin” by typing “cd /opt/mysql/mysql/bin“.
2. Type “./mysqladmin -u world_dba -h <IP for SQL Node> shutdown“. Just replace the IP with either mysqlserv1′s IP at 192.168.2.51 or mysqlserv2′s IP at 192.168.2.52

How To Stop The Data Nodes

You can always stop the Data Nodes through the Management Server’s console. From here, instead of using the IP of the data node, the NodeId is needed in this procedure. Just log into the terminal of the management server as the “mysql” user and perform the below:

1. Change the working directory to /opt/mysql/mysql/bin by typing “cd /opt/mysql/mysql/bin“
2. Open the NDB Management console by typing “./ndb_mgm“. You’ll be leaded to the ndb_mgm> prompt.
3. You may type “show” at the ndb_mgm> prompt to list all data nodes, showing their respective NodeIDs.
4. To stop the data node, just type “<NodeID> stop” with <NodeID> as the NodeId of the data node. e.g. “21 stop” to stop mysqldn1 192.168.2.53 or “22 stop” to stop mysqldn2 192.168.2.54 and so on.

How To Stop The Management Server

Before you stop the Management Server, it is always a good practice to first stop the SQL Nodes before doing so. Anyway, stopping the Management Server is the easiest. Just perform the below as “mysql” user in the terminal:

1. Change the working directory to /opt/mysql/mysql/bin by typing “cd /opt/mysql/mysql/bin“
2. Open the NDB Management console by typing “./ndb_mgm“. You’ll be leaded to the ndb_mgm> prompt.
3. Just type “shutdown” in the ndb_mgm> prompt. This command will first shutdown all data nodes controlled by the management server, then the management server itself. It is one of the most convenient way if you want to stop all data nodes and management server together at the same time.

To Be Continued…

For the next part of the tutorial, we’ll discuss more on testing procedures. Since clustering is suppose to promote high availability, we’ll try to distort the servers within the cluster and see if they do actually synchronize the data when nodes are revived. So, stay tune.

Proceed to Part 3:

MySQL Cluster NDB 7.2 on Solaris 10 Part 3 – Testing The Cluster

Related Articles:

• MySQL Cluster NDB 7.2 on Solaris 10 Part 1 – How To Install, Setup and Configure
• Installing MySQL 5.0 on Solaris 10
• Installing MySQL 5.5 on Solaris 10
• How To Boot MySQL 5.5 On Solaris 10 During System Startup

Assumptions and Disclaimer:

• Readers are assumed to have at least some basic Unix/Linux administrative skills.
• Readers are assumed to have FRESH running copy of Solaris 10 8/11 (u10-ga2).
• Readers are assumed to have NO previously installed MySQL version in the system.
• Readers are assumed to have backed up any critical data before the installation.
• The MySQL Cluster NDB version used for this tutorial is 7.2.8 (GA) Generally Available Release
• Readers are to take full responsibility of any potential software, data, hardware, financial and life damages prior to following this tutorial.

What Is Required In A MySQL Cluster?

Let’s go through this very quickly for knowledge sake. In a MySQL clustered environment, what is required are only the 3 components below:

Servers Preparation:

Once you have understood what SQL Nodes, Data Nodes and Management Server are, Without further ado, the server topology in the diagram below is what this tutorial focuses on deploying (just click on the diagram to expend). You may improvise to fit to your needs later; but for now and let’s get things started with this:

The Intended Demo MySQL Cluster Server Topology

Here, we have altogether 7 servers involved (2 SQL Nodes, 4 Data Nodes in groups of 2 and 1 management server) each with the same hardware specs of the below. You may always use VMWare, Oracle’s Virtual Box or other virtualization software to create these virtual machines with the below specs:

• 1 CPU: X86-64 base
• 40GB harddisk space
• 1GB of RAM
• Installed OS: Solaris 10 8/11 (u10 ga2 for Intel x86-64)

In my opinion, this hardware (or rather virtual hardware) configuration is just nice and not too superficial for a demo and for actual production implementation.

All the servers shown in the diagram carries IP, hostname and node IDs listed below:

The contents in the table will be for our reference. Please don’t worry much about the data directory location, the .cnf files and the config.ini file for now, we’ll go through that later.

Installing And Setting Up The Cluster – Let’s Rock!

Starting from here, it is time for hands on installation and setting up the cluster. Let’s do this step by step. Please don’t rush through it. I highly suggest that you double check every step before you move on and you should be able to get the cluster up and running in no time. By the way, keep SSH handy, that’s a very snappy tool and you’ll need it for speed.

Downloads

Please obtain a copy of the latest MySQL Cluster NDB 7.2.x from http://www.mysql.com/downloads/cluster/. YOU NEED THIS FOR ALL THE SERVERS. For the Solaris 10 MySQL Cluster NDB packages, please click on the select box under “Select Platform:” and select “Sun Solaris“. Choose the appropriate processor architecture of the package (either x86, 32-bit, x86, 64-bit or SPARC). Download the package and save them in an appropriate directory (this tutorial will deal with the file which ends with the Compressed Package – “.pkg.gz” extension, so you should download it instead of the Compressed Tar – “.tar.gz” version. At the time of writing, the latest MySQL Cluster NDB made available was version 7.2.8. The downloadable distribution’s file name on the download page is named with the format mysql-cluster-gpl-xxx.pkg.gz, just choose the system/processor architecture that is suitable to your system.

I will use “/usr/files” as the directory in all the servers where the mysql-cluster-gpl-xxx.pkg.gz file is placed throughout the tutorial (Please take note that the xxx is the architecture and version number and is to be replaced by the actual text in the file name).

Installing The MySQL Cluster NDB 7.2.x Package

Please perform the following as the “root” user. We have to make sure that any other previously running copies of MySQL are to be uninstalled from the system. Just follow the instructions below.

For EACH servers, perform the following as “root” user:

1. Login as “root” through the terminal.
2. The very first thing to do is to create the mysql group and user. To create the group, type: “groupadd mysql“.
3. Then create the mysql user by typing: “useradd -g mysql mysql“.
4. To list all the packages, type: “pkginfo | grep mysql” at the shell. On my system, I am able to see the below:
   

   # pkginfo | grep mysql
   system	SUNWmysqlr	mysql - MySQL Database Management System (root component)
   system	SUNWmysqlt	mysql - MySQL Database Management System (test component)
   system	SUNWmysqlu	mysql - MySQL Database Management System (usr component)
   

5. You may remove the listed packages by typing “pkgrm “. The names of the packages are list at the second column of after executing pkginfo. For my system, I will remove the listed packages by typing “pkgrm SUNWmysqlr SUNWmysqlt SUNWmysqlu“.
6. Change the directory to the place where you’ve downloaded the mysql-cluster-gpl-xxx.pkg.gz file. (e.g. “cd /usr/files“). If the file is compressed by gzip and you can see the .gz extension at the end of the file, you may decompress it by typing “gzip –d mysql-cluster-gpl-xxx.pkg.gz“. Once the file had been decompressed, you should be able to see mysql-cluster-gpl-xxx.pkg by typing the list command “ls”.
7. Install the package by typing “pkgadd -d mysql-cluster-gpl-xxx.pkg” and accept all the defaults.
8. Repeat step 1 to 7 for ALL SERVERS (from 192.168.2.50 to 192.168.2.56).

Preparing The Necessary Directories

Once the package had been installed, we’ll have to create some directories to store the database’s data and configuration files. The MySQL installation does access to default directories, but it will be better for you to know which and where the data files and the most recent executing running configuration files are stored and accessed. It is easier for modification and maintenance in the long run.

Ownership and Permission For All Necessary Directories

After installing the MySQL Cluster NDB package and creating all the directories mentioned above, this is the time to change the ownership and the permission of the directories.

For EACH server, perform this as the “root” user:

1. In the terminal, change the ownership of the directories by typing “chown –R mysql:mysql /opt/mysql /var/mysql“
2. Change the file permissions recursively by typing “chmod –R 755 /opt/mysql /var/mysql“.
3. Please repeat step 1 to 2 for all servers.

Configuration for MySQL Server (SQL Nodes Only)

Remember the current-running-config-files directory that you’ve created in /opt/mysql/mysql? This is the time to create config files for the SQL Nodes. Just follow the instructions below and do this ONLY on mysqlserv1 (192.168.2.51) and mysqlserv2 (192.168.2.52):

Perform the below as the “mysql” user for both mysqlserv1 (192.168.2.51) and mysqlserv2 (192.168.2.52):

• Switch to the user by typing “su mysql” in the terminal.
• Change the directory to /opt/mysql/mysq/current-running-config-files by typing “cd /opt/mysql/mysq/current-running-config-files“.
• Create a file “mysql.mysqlserv1.cnf” by typing “touch mysql.mysqlserv1.cnf“. This is for mysqlserver1. As for mysqlserver2, just create a file name “mysql.mysqlserv2.cnf” with the same procedure.
• Edit the newly created mysql.<hostname>.cnf with the contents below:
  

  [mysqld]
  # run NDB storage engine
  ndbcluster
  
  # location of management server
  ndb-connectstring=192.168.2.50
  
  # define the location of the data directory
  datadir=/var/mysql/cluster-data/mysqlserv1
  
  #The rest of the configuration values
  
  [mysql_cluster]
  # location of management server
  ndb-connectstring=192.168.2.50
  
  

  
  The above is for mysqlserv1 (192.168.2.51), please replace the line “datadir=/var/mysql/cluster-data/mysqlserv1” to “datadir=/var/mysql/cluster-data/mysqlserv2” for mysqlserv2 (192.168.2.52). Besides storing configuration parameters in the .cnf file, what we have defined here is to tell the SQL Node that the Management Server lies in 192.168.2.50 and it has to be tame by it. You may even define the “[client]” section and amend the “[mysqld]” section with the necessary configuration parameters for optimization purposes, just look at the /opt/mysql/mysql/support-files/ directory for some ideas. But for now, this is sufficient.

In future, for every SQL Node that you add, the above will be the reference configuration for your usage.

Configuration for Management Server (Only for mysqlmngserv)

Now, we need to create the config.ini file for only the Management Server and this is a crucial step. Just follow the instructions below:

Perform this as the “mysql” user on ONLY the mysqlmngserv (192.168.2.50):

1. Switch to the user “mysql” by typing in the terminal “su mysql“.
2. Change the directory to /opt/mysql/mysql/current-running-config-files by typing “cd /opt/mysql/mysql/current-running-config-files“.
3. Create a file name config.ini by typing “touch config.ini“.
4. Edit the newly created config.ini file with the contents below:
   

   [ndbd default]
   # Number of replicas
   # We want 2 data nodes within 1 group e.g. Data Node 1 and
   # Data Node 2 belongs to one group, etc.
   NoOfReplicas=2
   
   [ndb_mgmd]
   #specify the node id of the management server
   NodeId=1
   
   #hostname or IP of the management server
   hostname=192.168.2.50
   
   # The data directory for the management server
   datadir=/var/mysql/cluster-data/mysqlmngserv
   
   # For the below, for every Data Node, just specify a section call "[ndbd]"
   # Configs for Data Node 1
   [ndbd]
   #specify the node id for the Data Node
   NodeId=11
   hostname=192.168.2.53
   datadir=/var/mysql/cluster-data/mysqldn1
   
   # Configs for Data Node 2
   [ndbd]
   NodeId=12
   hostname=192.168.2.54
   datadir=/var/mysql/cluster-data/mysqldn2
   
   # Configs for Data Node 3
   [ndbd]
   NodeId=13
   hostname=192.168.2.55
   datadir=/var/mysql/cluster-data/mysqldn3
   
   # Configs for Data Node 4
   [ndbd]
   NodeId=14
   hostname=192.168.2.56
   datadir=/var/mysql/cluster-data/mysqldn4
   
   # Same goes, for every SQL Node, just specify a section call "[mysqld]"
   # You don't have to specify the data directory for the SQL Nodes here.
   # Configs for MySQL Server 1
   [mysqld]
   #specify the node id for the MySQL Server
   NodeId=31
   hostname=192.168.2.51
   
   # Configs for MySQL Server 2
   [mysqld]
   NodeId=32
   hostname=192.168.2.52
   

5. Save the amendments in config.ini

Just a brief explanation on config.ini: for every Data Node that is involve in the cluster, you will need to define a “[ndbd]” section for each of it, with the specific NodeId, hostname (which points to the IP address of the data node server) and datadir (which is the data directory on the data node server itself, not the management server). Likewise for the MySQL Server (SQL Nodes), there should be a “[mysqld]” section defined for each SQL Nodes with the NodeId and the hostname parameter.

Notice the NoOfReplicas parameter? That is the parameter that is use to tell the management server how many data nodes should be within a single group. Here, the value for NoOfReplicas is 2, which means, there should be 2 data nodes within one data node group. Therefore, the equation below holds true:

To Be Continued…

Hope that everything is fine when you reach here. Because of the length of the tutorial, a decision was made to separate it into several parts. For the next part, we’ll discuss more on how to start, how to manage the MySQL users (user and privilege synchronization) in the cluster/distributed environment and how to stop the servers in the cluster. So, read on…

Proceed to Part 2:

MySQL Cluster NDB 7.2 on Solaris 10 Part 2 – Starting, Distributed Synchronized Users Management And Stopping The Cluster

Related Articles:

• MySQL Cluster NDB 7.2 on Solaris 10 Part 3 – Testing The Cluster
• Installing MySQL 5.0 on Solaris 10
• Installing MySQL 5.5 on Solaris 10
• How To Boot MySQL 5.5 On Solaris 10 During System Startup

Calling C:\Java\jboss-6.1.0-final\bin\run.conf.bat
===============================================================================

  JBoss Bootstrap Environment

  JBOSS_HOME: C:\Java\jboss-6.1.0-final

  JAVA: C:\Program Files\Java\jdk1.6.0_30\bin\java

  JAVA_OPTS: -Dprogram.name=run.bat -Dlogging.configuration=file:logging.properties \
-Xms128m -Xmx512m -XX:MaxPermSize=256m -server

  CLASSPATH: C:\Program Files\Java\jdk1.6.0_30\lib\tools.jar;C:\Java\jboss-6.1.0-final\bin\run.jar

===============================================================================

Unable to read the logging configuration from 'file:logging.properties' (java.io.FileNotFoundException:
logging.properties (The system cannot find the file specified))

Solution for Microsoft Windows

If you are running on windows, you can fix this issue before you start the JBoss server through Netbeans:

1. Go to the “bin” directory where you’ve installed JBoss
2. Edit the “run.bat” file
3. Search for the line “set JAVA_OPTS=-Dprogram.name=%PROGNAME% -Dlogging.configuration=file:%DIRNAME%logging.properties %JAVA_OPTS%“

4. Change the %DIRNAME% to your absolute path to the “bin” directory of your installed JBoss.e.g.

   set JAVA_OPTS=-Dprogram.name=%PROGNAME% -Dlogging.configuration=file:”C:\Java\jboss-6.1.0-final\bin\logging.properties” %JAVA_OPTS%

5. I’m adding the double quote ” so that if your directory name has spaces, it will still be legitimate.
6. Try to start your server through Netbeans again, it should be working fine after this.

Solution for Unix/Linux

If you are running on any flavor of Unix or Linux, you can fix this issue before you start the JBoss server through Netbeans:

1. Go to the “bin” directory where you’ve installed JBoss
2. Edit the “run.sh” file
3. Search for the line JAVA_OPTS=”${JAVA_OPTS:+$JAVA_OPTS -Dlogging.configuration=file:${DIRNAME}/logging.properties}”

4. Change the ${DIRNAME} to your absolute path to the “bin” directory of your installed JBoss.e.g.

   JAVA_OPTS=”${JAVA_OPTS:+$JAVA_OPTS -Dlogging.configuration=file:/java/jboss-6.1.0-final/bin/logging.properties}”

5. Try to start your server through Netbeans again, it should be working fine after this.

Hope it helps.

STICKY IMPORTANT HIGHLIGHT!!!:
** You can only bring out the effects of transaction attributes only when you call the method through a
session bean instance and NOT through a direct method call. Even if your methods are within the same
bean, you need to get the local instance of the same bean and call through its local interface instead
of a direct method invoke.

When to use TransactionAttributeType.NEVER

In my opinion, a method should be annotated with TransactionAttributeType.NEVER if it only consist of logics that “NEVER” touches the database or any invocation of other methods which are transactional. Thus, the word NEVER.

For my past projects, I’ll annotate session bean methods with NEVER if they are only specifically involve in physical file reading and writing (I’ll skip the debates on EJB specs), raw number crunching, cropping/transformation/editing of an image, algorithms which serves an algorithmic purpose (funny, but it makes sense e.g. calculation of the upper and lower Bollinger bands for financial numbers) or even password encryption and decryption. These are just some of the examples of usage for methods with NEVER transaction attribute type. Notice that the above use cases didn’t touch any database layer and whatever the method processes, it is final and no correction when things go wrong. If you have specific use cases like this, NEVER is just the answer to your session bean method.

The benefits of using TransactionAttributeType.NEVER is it doesn’t involve any database transaction and thus it has limited overhead in usage of app server resources.

Transaction Attribute Types That “NEVER” Co-exists:

A session bean method that is annotated as NEVER is safe to be invoked by another session bean method that is annotated by TransactionAttributeType.NOT_SUPPORTED, as it will suspend any transaction before carrying out its business.

Summary

I hope that you have gain much by reading all of this 4 part series of transaction attributes. Knowing the behavior of the attribute type will just increase your knowledge, but knowing when to use them at the right time in the right places will do wonders in your application.

Hope you’ve enjoy reading.

Related Articles:

• Making sense of EJB3.x Transaction Attributes – Part 1 (REQUIRES_NEW)
• Making sense of EJB3.x Transaction Attributes – Part 2 (MANDATORY)
• Making sense of EJB3.x Transaction Attributes – Part 3 (Difference Between SUPPORTS and NOT_SUPPORTED)

Behavior of SUPPORTS and NOT_SUPPORTED

Just briefly take a look at the code snippet below:

@Local
public interface ISessionFacade1 {
	public void method1();
	public void method2();
}

@Stateless
public class SessionFacade1 implements ISessionFacade1
{
	@TransactionAttribute( TransactionAttributeType.SUPPORTS)
	public void method1() {
		//Do Something...
	}

	@TransactionAttribute( TransactionAttributeType.NOT_SUPPORTED)
	public void method2() {
		//Do Something...
	}		
}

public class SessionFacade2
{
	@EJB
	private ISessionFacade1 sf1;

	public void performBusinessLogic()
	{
                /**
                 * For sf1.method1() will will ride on the same transaction that is
                 * within performBusinessLogic()
                 */
		sf1.method1();

		/**
                 * As for sf1.method2(), it will just suspend the transaction within
                 * performBusinessLogic(), run it by its own and resume the transaction again.
                 */
		sf2.method2();
	}	

}

Right here, we have both stateless session bean of SessionFacade1 (implementing ISessionFacade1local interface) and SessionFacade2. In SessionFacade1, we have 2 methods where by method1() was annotated with @TransactionAttribute(TransactionAttributeType.SUPPORTS) and method2() was annotated with @TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED). Now, if performBusinessLogic() in SessionFacade2 runs and invokes method1() in SessionFacade1, since method1() was annotated with SUPPORTS, it will ride on the same transaction as performBusinessLogic(). If performBusinessLogic() has transaction T1, method1() will also use the same transaction T1 as performBusinessLogic(). But if any external invocation on method1() is without a transaction, method1() won’t start its own transaction and will just execute without a transaction.

The interesting part lies in method2() of SessionFacade2. When performBusinessLogic() invokes method2(), even if performBusinessLogic() carries a transaction T1 (T1 is just a name given), method2() will neither ride on T1 nor will it start its own transaction. It will simply suspend T1 or whatever transaction that the external invoker has, execute its individual contents, only then the transaction T1 will be resumed after that. Simple said, any methods with NOT_SUPPORTED are non-transactional and will not participate in any existing transactions; it won’t throw an error whether if it is within a transaction or not, but it just won’t participate in a transaction.

STICKY IMPORTANT HIGHLIGHT!!!:
** You can only bring out the effects of transaction attributes only when you call the method through a
session bean instance and NOT through a direct method call. Even if your methods are within the same
bean, you need to get the local instance of the same bean and call through its local interface instead
of a direct method invoke.

Need an Example?

OK, enough theories, I’m gonna give you a very simple example of how the data is being affected by just executing 2 methods of the same code contents but with different democrat. One with SUPPORTS and another with NOT_SUPPORTED.

The below is the a simple single database table (MySQL orientated) which encapsulates a bank account holder with the current balance in his or her bank account.

In this superficial table, the USERNAME column represents the bank account holder and the ACCT_BALANCE column represents the current account balance in terms of money. Let’s populate the table with 2 users, “DUMMY1” with $100,000 and “DUMMY2” with $1,000,000. You may use the script below to generate the table and the data.

CREATE TABLE BANK_ACCOUNT
(
    PK BIGINT NOT NULL AUTO_INCREMENT,
    USERNAME VARCHAR(255) NOT NULL,
    ACCT_BALANCE DECIMAL(12,2) NOT NULL,
    PRIMARY KEY(PK),
    UNIQUE(USERNAME)
) ENGINE=InnoDB;
 
INSERT INTO BANK_ACCOUNT (USERNAME, ACCT_BALANCE) VALUES ('DUMMY1', 100000);
INSERT INTO BANK_ACCOUNT (USERNAME, ACCT_BALANCE) VALUES ('DUMMY2', 1000000);

The below are the codes with the entity class (BankAccountEntity.java):

package com.developerscrappad.entity;
 
import java.io.Serializable;
import java.math.BigDecimal;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.NamedQueries;
import javax.persistence.NamedQuery;
import javax.persistence.Table;
 
@Entity
@Table(name = "BANK_ACCOUNT")
@NamedQueries({
    @NamedQuery(name = "BankAccountEntity.findByPk", query = "SELECT b FROM BankAccountEntity b WHERE b.pk = :pk"),
    @NamedQuery(name = "BankAccountEntity.findByUsername", query = "SELECT b FROM BankAccountEntity b WHERE b.username = :username")})
public class BankAccountEntity implements Serializable {
 
    private static final long serialVersionUID = -7053090916337791292L;
 
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "PK")
    private Long pk;
 
    @Column(name = "USERNAME")
    private String username;
 
    @Column(name = "ACCT_BALANCE")
    private BigDecimal acctBalance;
 
    public BankAccountEntity() {
    }
 
    public BankAccountEntity(Long pk) {
        this.pk = pk;
    }
 
    public BankAccountEntity(Long pk, String username, BigDecimal acctBalance) {
        this.pk = pk;
        this.username = username;
        this.acctBalance = acctBalance;
    }
 
    public Long getPk() {
        return pk;
    }
 
    public void setPk(Long pk) {
        this.pk = pk;
    }
 
    public String getUsername() {
        return username;
    }
 
    public void setUsername(String username) {
        this.username = username;
    }
 
    public BigDecimal getAcctBalance() {
        return acctBalance;
    }
 
    public void setAcctBalance(BigDecimal acctBalance) {
        this.acctBalance = acctBalance;
    }
 
    @Override
    public int hashCode() {
        int hash = 0;
        hash += (pk != null ? pk.hashCode() : 0);
        return hash;
    }
 
    @Override
    public boolean equals(Object object) {
        // TODO: Warning - this method won't work in the case the id fields are not set
        if (!(object instanceof BankAccountEntity)) {
            return false;
        }
        BankAccountEntity other = (BankAccountEntity) object;
        if ((this.pk == null && other.pk != null) || (this.pk != null && !this.pk.equals(other.pk))) {
            return false;
        }
        return true;
    }
 
    @Override
    public String toString() {
        return "com.developerscrappad.entity.BankAccountEntity[ pk=" + pk + " ]";
    }
}

Here, let’s have 2 stateless session beans where by BankQuerySessionFacade‘s methods are to only perform querying of the accounts and BankTransactionSessionFacade will have a method to perform fund transfer between accounts of different account holders. All with necessary @Local interfaces

Codes for interface IBankQuerySessionFacadeLocal:

package com.developerscrappad.ejb;
 
import com.developerscrappad.entity.BankAccountEntity;
import javax.ejb.Local;
 
@Local
public interface IBankQuerySessionFacadeLocal {
 
    public BankAccountEntity findBankAccountByUsernameWithSupports(String username);
 
    public BankAccountEntity findBankAccountByUsernameWithNotSupported(String username);
}

Codes for interface IBankQuerySessionFacadeRemote:

package com.developerscrappad.ejb;
 
import javax.ejb.Remote;
 
@Remote
public interface IBankQuerySessionFacadeRemote extends IBankQuerySessionFacadeLocal {
}

Codes for BankQuerySessionFacade (which is specifically for querying purposes):

package com.developerscrappad.ejb;
 
import com.developerscrappad.entity.BankAccountEntity;
import javax.ejb.Stateless;
import javax.ejb.TransactionAttribute;
import javax.ejb.TransactionAttributeType;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
import javax.persistence.Query;
 
@Stateless
public class BankQuerySessionFacade implements IBankQuerySessionFacadeLocal, IBankQuerySessionFacadeRemote {
 
    @PersistenceContext(unitName = "YourPersistentUnitName")
    private EntityManager em;
 
    protected EntityManager getEntityManager() {
        return em;
    }
 
    private BankAccountEntity findBankAccountByUsername(String username) {
        Query q = getEntityManager().createNamedQuery("BankAccountEntity.findByUsername");
        q.setParameter("username", username);
 
        return (BankAccountEntity) q.getSingleResult();
    }
 
    @Override
    @TransactionAttribute( TransactionAttributeType.SUPPORTS)
    public BankAccountEntity findBankAccountByUsernameWithSupports(String username) {
        return findBankAccountByUsername(username);
    }
 
    @Override
    @TransactionAttribute( TransactionAttributeType.NOT_SUPPORTED)
    public BankAccountEntity findBankAccountByUsernameWithNotSupported(String username) {
        return findBankAccountByUsername(username);
    }
}

Codes for IBankTransactionSessionFacadeLocal:

package com.developerscrappad.ejb;
 
import java.math.BigDecimal;
import javax.ejb.Local;
 
@Local
public interface IBankTransactionSessionFacadeLocal {
 
    public void performFundTransfer(String fromUsername, String toUsername, BigDecimal transferAmount) throws Exception;
}

Codes for IBankTransactionSessionFacadeRemote:

package com.developerscrappad.ejb;
 
import javax.ejb.Remote;
 
@Remote
public interface IBankTransactionSessionFacadeRemote extends IBankTransactionSessionFacadeLocal {
}

Codes for BankTransactionSessionFacade (this is where the transaction content lies):

package com.developerscrappad.ejb;
 
import com.developerscrappad.entity.BankAccountEntity;
import com.sun.istack.logging.Logger;
import java.math.BigDecimal;
import javax.ejb.EJB;
import javax.ejb.Stateless;
import javax.ejb.TransactionAttribute;
import javax.ejb.TransactionAttributeType;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
 
@Stateless
public class BankTransactionSessionFacade implements IBankTransactionSessionFacadeLocal, IBankTransactionSessionFacadeRemote {
 
    private Logger log = Logger.getLogger(BankTransactionSessionFacade.class);
 
    @PersistenceContext(unitName = "YourPersistentUnitName")
    private EntityManager em;
 
    @EJB
    private IBankQuerySessionFacadeLocal bankQuerySF;
 
    @Override
    @TransactionAttribute(TransactionAttributeType.REQUIRED)
    public void performFundTransfer(String fromUsername, String toUsername, BigDecimal transferAmount) throws Exception {
 
        BankAccountEntity fromBankAccount = bankQuerySF.findBankAccountByUsernameWithSupports(fromUsername);
        BankAccountEntity toBankAccount = bankQuerySF.findBankAccountByUsernameWithSupports(toUsername);
 
        //Check if the funds are enough for transfer
        if (fromBankAccount.getAcctBalance().compareTo(transferAmount) == -1) {
            throw new Exception("Insufficient funds");
        }
 
        //Perform the transfer
        fromBankAccount.setAcctBalance(fromBankAccount.getAcctBalance().subtract(transferAmount));
        toBankAccount.setAcctBalance(toBankAccount.getAcctBalance().add(transferAmount));
 
        em.persist(fromBankAccount);
        em.persist(toBankAccount);
        em.flush();
 
        //This portion is for analysis, checking and illustration purposes
        BankAccountEntity fromBankAccount1 = bankQuerySF.findBankAccountByUsernameWithSupports(fromUsername);
        BankAccountEntity fromBankAccount2 = bankQuerySF.findBankAccountByUsernameWithNotSupported(fromUsername);
 
        /**
         * For the below log trace, fromBankAccount1 amount should show the
         * deducted amount from fromUsername, BUT, the fromBankAccount2 amount
         * will still show the original amount balance from fromUsername!
         */
        log.fine("fromBankAccount1 amount: " + fromBankAccount1.getAcctBalance());
        log.fine("fromBankAccount2 amount: " + fromBankAccount2.getAcctBalance());
    }
}

What we are about to do here is to perform a fund transfer of $10,000 from the account of “DUMMY2” to the the account of “DUMMY1“. This is done in BankTransactionSessionFacade‘s performFundTransfer() method. But meanwhile, the purpose is to examine the BankAccountEntity object of the same username if we query the BankAccountEntity object with both SUPPORTS and NOT_SUPPORTED transaction attribute type.

So, we have a client code to invoke performFundTransfer() e.g.:

Context ctx = new InitialContext();
IBankTransactionSessionFacadeRemote remote = (IBankTransactionSessionFacadeRemote) \
 ctx.lookup(IBankTransactionSessionFacadeRemote.class.getName());

remote.performFundTransfer("DUMMY2", "DUMMY1", new BigDecimal(10000));

If you execute the above code snippet, the transfer happened in the BankTransactionSessionFacade.performFundTransfer will persist well for both fromBankAccount (which belongs to username “DUMMY2“) and toBankAccount (which belongs to username “DUMMY1“).

Now for the fun part, when we again query the account belonging to “DUMMY2” through both BankQuerySessionFacade.findBankAccountByUsernameWithSupports() method and BankQuerySessionFacade.findBankAccountByUsernameWithNotSupported()method like the later portion of codes of BankTransactionSessionFacade:

BankAccountEntity fromBankAccount1 = \
bankQuerySF.findBankAccountByUsernameWithSupports(fromUsername);
BankAccountEntity fromBankAccount2 = \
bankQuerySF.findBankAccountByUsernameWithNotSupported(fromUsername);

log.fine("fromBankAccount1 amount: " + fromBankAccount1.getAcctBalance());
log.fine("fromBankAccount2 amount: " + fromBankAccount2.getAcctBalance());

fromBankAccount1 entity object will rightfully reflect the deducted amount from DUMMY2, which is $990,000. But for fromBankAccount2, the the getAcctBalance() will yield the same unchanged account balance value of $1,000,000. This is because for BankQuerySessionFacade.findBankAccountByUsernameWithSupports() method, it queries within the same transaction used in BankTransactionSessionFacade.performFundTransfer() and the data righly reflects all that has happened within the transaction; but for BankQuerySessionFacade.findBankAccountByUsernameWithNotSupported(), it suspends the transaction running within BankTransactionSessionFacade.performFundTransfer() and queries what is still stored in the database before the BankTransactionSessionFacade.performFundTransfer() commits when it leaves the method.

So with this, we could draw some conclusion between SUPPORTS and NOT_SUPPORTED.

When to use TransactionAttributeType.SUPPORTS?

This is not absolute, but in my opinion and after going through myriads of projects with Java EE, I would annotate TransactionAttributeType.SUPPORTS on methods that query objects which the underlying data is consistently updated (constantly changing) and would always be involved in other transaction methods that carries Transaction Attribute Types like REQUIRED, MANDATORY or REQUIRES_NEW.

Query methods for changing data are well suited to be annotated with SUPPORTS because if the method only queries even without transaction, it could still return the data while not having to cause transaction overhead.

But on the contrary, if you annotate a method which performs persisting, merging or deletion of data in the database, use SUPPORTS wisely with discerning care.

When to use TransactionAttributeType.NOT_SUPPORTED?

TransactionAttributeType.NOT_SUPPORTED are better suited for methods that query objects which carries static data that won’t be expected to be changed or to be transactionally involved with other business transaction. It can be querying methods for statically permanent data like country list, region list, gender list, etc. Methods that query data to especially establish drop-down list options in the selection box of web-forms are very well suited to be annotated with NOT_SUPPORTED.

Annotating NOT_SUPPORTED in methods like these will greatly save applications from transaction overhead(s).

Summary

We have seen from the previous posts on REQUIRES_NEW and MANDATORY (REQUIRED included) that are mostly used for heavy transactionally orientated processes for data persisting, merging and deletion. But both SUPPORTS and NOT_SUPPORTED are just right for methods that performs data query instead of writing stuff back into the database.

Overall, for methods that are annotated with SUPPORTS, it can be part of a transaction context and it can run even without transaction, that makes it suitable for querying of constantly changing data. Whereas for methods that are annotated with NOT_SUPPORTED, it will just suspend any transaction if it is run within a transaction context, thus making it suitable to for querying any data which is non-changing, static and permanent.

I hope this article truly makes sense out of SUPPORTS and NOT_SUPPORTED transaction attribute types. Thank you for reading and happy coding.

Related Articles

• Making sense of EJB3.x Transaction Attributes – Part 1 (REQUIRES_NEW)
• Making sense of EJB3.x Transaction Attributes – Part 2 (MANDATORY)
• Making sense of EJB3.x Transaction Attributes – Part 4 (NEVER)