Morphia query example : exists() and doesNotExist()

Morphia query example : exists() and doesNotExist()

Morphia does not save empty fields by default. So when an entity attribute is null, the default behavior is to ignore it and not store it on the server side. The exists() method of the fluent Query API allows us to test if a field exists in the mongoDB document while doesNotExist() tests the exact opposite. They both correspont to the $exists mongoDB query operator.

exists() and doesNotExist() query example :

console output :


Morphia documentation wiki @

Morphia Query official documentation

MongoDB $exists documentation


Morphia query example : hasAnyOf() and hasNoneOf()

Morphia query example : hasAnyOf() and hasNoneOf()

Like the IN operator in SQL, hasAnyOf() lets you test against multiple values for the field you are querying on. If any of these values matches the field’s value, then the entity will be returned. hasAnyOf() corresponds to the $in operator of mongoDB.

hasNoneOf() works the exact oposite way: if any of the tested values match the content of the field, the entity will not be considered a match to your query. hasNoneOf() corresponds to the $nin operator of mongoDB. You can also use both methods to test an array or collection field in your entity, in which case, an entity / document will be a match if ANY of the values in the field match ANY of the values of the query.


hasAnyOf() and hasNoneOf() example :

Notice that in the  hasAnyOf() example above will return entities where the interests field either contains chocolate OR sport cars. If you need to find users interested in chocolate AND sport cars you need to build and AND clause either implicitly or explicitely. The easiest way of doing is to do it by using the hasAllOf() method detailed in a subsequent post.


Morphia documentation wiki @

Morphia Query official documentation

MongoDB $in documentation

MongoDB $nin documentation


Morphia query example : greaterThan(), lessThan(), greaterThanOrEq(), lessThanOrEq()

Morphia query example : greaterThan(), lessThan(), greaterThanOrEq(), lessThanOrEq()

Morphia’s fluent api allows you to perform queries using comparison on a given field.
greaterThan() and lessThan() correspond to the $gt and $lt mongoDB operators respectively. As their name implies, they allow you to perform greater than or less than queries.
greaterThanOrEq() and lessThanOrEq() correspond to the $gte and $lte mongoDB operators respectively. This time they allow you to perform greater than or equals or less than or equals comparisons for your queries.

Note that if the tested field is an array or collection, the query will return entities where at least one of the entries in the array match the comparison.



Morphia documentation wiki @

Morphia Query official documentation

MongoDB $gt documentation

MongoDB $lt documentation

MongoDB $gte documentation

MongoDB $lte documentation

Morphia query example : equal(), notEqual() and hasThisOne()

Morphia query example : equal(), notEqual() and hasThisOne()

When querying using Morphia’s fluent API you will often need to select entities by using equality comparison. This is pretty much the same as using the WHERE x=y clause in SQL databases.

equal() and hasThisOne() correspond to the $eq operator in mongoDB. They both work exactly the same way although you might prefer to use hasThisOne() on array fields for code readbility.

notEqual() corresponds to the  $ne mongoDB operator and works the opposite way by testing for field inequality.  Note that when the tested entity field is an array or collection, the query will return entities where at least one entry in the array matches the passed value.


equal(), notEqual() and hasThisOne() example :



output :

User where login equal() Foo : login = Foo – carBrand = audi
sportsCarsLovers with hasThisOne() :
sportsCarsLovers with equal() :
nonFerrariOwners notEqual() :
nonFerrariOwnersNonAudiOwners multiple notEqual() combined


Note : when chaining queries, the default behaviour of the API is to combine them with an AND clause. So in the last example above you could read the last query as SELECT users where firstName equals “Alex” AND lastName not equals “Foobar” .



Morphia documentation wiki @

Morphia Query official documentation

MongoDB $eq documentation

MongoDB $ne documentation




Bluehost shared SSL : WordPress Configuration

Bluehost Shared SSL : WordPress Configuration

If you’ve subscribed for a Bluehost basic plan to host your wordpress blog, you can securely log in to your wordpress install without having to buy a dedicated IP or 200$ SSL certificate of you own. You can simply use the shared SSL certificate kindly provided by Bluehost. It however requires a little trick to work properly with wordpress.

1 – Find Your Bluehost Hostname

The first thing to do is to log into your bluehost cPanel to find the name of the machine / server your site is hosted on. As per this documentation  it is located in the stats column of your cPanel under the Hostname entry . You might need to expand the stats column to see it.  Here’s how it looks like at the time of writing :



2 – Build Your Secure wp-admin URL

With that information you are now able to rebuild the secure url pointing to the wp-admin area of your wordpress install. It will be in the form :

replace the XYZ with the actual number of the server of your bluebox install and ~username with your actual bluebox username. Now don’t go there yet! Worpress does not like this URL… it doesn’t care about it and you will eventually end up in a redirect loop of some kind.


3- modify your wp-config.php

To make things work you need a little hacking of your wp-config.php file.

Launch your FTP client, go to your wordpress install folder and find the file named wp-config.php. Make a backup of this file on your computer just in case. Now modify the file on your server and right after the opening comments add the following lines of code :

Once again modify the host part of the URL according to the actual host name of the box your website is hosted on. Plus, modify ~userName with your actual bluehost username.

Voilà !

Try the url you built above and you should be redirected to your wordpress login screen. Enter your credentials and you should be in ! Securely !

4 – Additional Tips

Now you might have some other problems coming up such as the urls of the images you insert into posts and the urls of the links to other pages of your blog.

Visit this page and follow the instructions to install the small fix Simen proposes.

All credit should go to Simen for his excellent explanation and plugin !

Enjoy !





Morphia query example basics

Morphia query example : basics

Morphia was built with type safety, validation, and code readability in mind. The org.mongodb.morphia.query.Query<T> class aims to allow the developer to fetch persisted entities from the datastore and convert them back to their Java counterpart in the most intuitive manner.  We will give you here and in subsequent posts, some basic morphia query examples.
To create a query you have two options : either call the createQuery(Class<?> type) method directly on your Datastore instance, or use an implementation of org.mongodb.morphia.dao.DAO (Data Access Object) and call createQuery() directly from this DAO. The former forces you to set the returning type as an argument on each call and you might be tempted to use it everywhere in your code. On the other hand, using the DAO offers more flexibility and prebuilt functionalities, with the notable addition of decoupling your core application logic from persistence logic.

Once you have created your Query object you can refine your search for persisted entities with the help of two methods : the filter() method and the field() method.

Here’s how it works :

1 – Basic Morphia Query example :

Here’s how you could query using the datastore directly.

query using Datastore :



2 – Query using DAO example :

The best approach architecture wise, is to declare specific data access methods in a dedicated DAO class that isolates the persistence related code, from  the rest of your application. Coding to a DAO interface allows you to completely swap persistence technologies or libraries whenever needed, without having to modify your application’s service layer for example.

file (interface) :

file (concrete class):

file (how to use your DAO)


3 – Query using the filter() method :

The Query.filter(String condition, Object value)  is the less verbose of the two filtering methods and allows you to create conditional statements for your query with a simple String and a simple value Object. The condition parameter should be made of the tested field’s name followed by the wanted conditional operator. You may use all of mongoDB’s regular conditional operators (e.g. $eq, $in, $gt etc…) when writing your condition parameter, but you may also use Morphia’s custom (and somewhat more intuitive) aliases detailed in Table-1 below. Here’s an example of how to use the filter() method :

filter() query examples :

As you can see, building a query in this manner is very straightforward, and might seem very familiar to mongoDB users. However some users might prefer the second approach available in morphia’s Query API : the fluent interface provided by the field() method.

Note : all of the filter() operators are available in the recap table at the bottom of this article.

4 – Query filtering using the field() method : the fluent API

Although the filter method lets you write short queries very quickly, the field() method offers better code readability and allows you to build more complex queries.  Using Query<T>.field(String fieldName) gives you access to the multiple filtering methods provided by the FieldEnd fluent interface.  You can use these methods to obtain the exact documents you need from the datastore by combining them in more complex queries. Although more verbose, the fluent API offers better readability than the filter() method. The methods provided by FieldEnd are detailed in the following articles :








Here is a recap table showing all the mongoDB operators, alongside their filter() aliases and field() counterparts :


mongoDB field() filter() operation
$eq equal() or
= or == equality test
$ne notEqual() != or <> inequality test
$gt greaterThan() > greater than test
$gte greaterThanOrEq() >= greater than or equal test
$lt lessThan() < less than test
$lte lessThanOrEq() <= less that or equal test
$exists exists() exists test for existance of field




References :

Morphia documentation : querying

MongoDB documentation : Query comparison operators

Morphia documentation wiki @ github

Morphia @Indexed example

In addition to defining what to persist and how, Morphia annotations let you set-up how the persisted entities should be indexed in the mongoDB store.
Propper indexation is of vital importance when query performance is involved, and two annotations are available in Morphia to define database side indexes :

@Indexed is used on the field level to define how a single field is to be indexed,

@Indexes is used on the class level to define compound and complex indexes that may involve multiple fields.

This short tutorial only focuses on the former @Indexed.

Morhia @Indexed example

As mentioned, the @Indexed can be applied on an entity’s field. It accepts various options that let you fine tune how the field is to be indexed by mongoDB.

Here’s  what a complete User entity with @Indexed  fields  might look like :




@Indexed in detail

Avaialable elements of the annotation are as follow :

Elements of the annotation :

element type default description
value IndexDirection ASC  allows to set the sort direction of the index. Choose one of the values provided by the org.mongodb.morphia.utils.IndexDirection enum. IndexDirection.ASC will sort the index in ascending order while IndexDirection. DESC in descending order. IndexDirection.GEO2D and IndexDirection.GEO2DSPHERE is used for spatial indexes on field that contains a latitude and longiture for example. The default value is IndexDirection.ASC.
name String empty stirng Allows to define how the index is named in the mongoDB collection.
unique boolean false Requires the indexed field’s value to be unique accross the collection. When saving an entity, Morphia (and mongoDB) will throw an error if you try to save duplicate values when the field is marked as unique. Default value is false.
dropDups boolean false Allows to drop duplicate values at index creation time for a field marked as unique. Use with caution.
background boolean false Allows to run the index creation in the background, preventing read and write operations to be blocked while the index is being created. Read this document and use with caution.
sparse boolean false Allows to create a sparse index that will not keep documents that do not have the provided field. See this document for more details.
expireAfterSeconds int -1 Allows to define a Time To Live index for the persisted documents. Use on a java.util.Date field to set the time at which the document should expire and be removed from the collection.


Important info : Morphia does not seem to lazily create indexes. You must explicitly tell it to create the indexes (at application startup time for example). For this you need to map the classes manually with your Morphia instance and then call ensureIndexes on the Datastore instance. Here is an example :


@Indexed IndexDirection example :

The default element of the @Indexed annotation allows you to set the direction of the index.  IndexDirection.ASC or IndexDirection.DESC can be used on any field containing standard numeric or string values.

Note : IndexDirection also has two other possible values which are IndexDirection.GEO2D and IndexDirection.GEO2DSPHERE related to indexing geographic data and which will be covered in a subsequent tutorial.


@Indexed ‘name’ example :

The ‘name’ element of the @Indexed annotation allows you to set the name of the index as it will be stored on the mongoDB server. If left empty, morphia will generate an index name for you in the form <fieldName> followed by _1 if the index is ascending or _-1

In this example the index name for the login field will be “login_1” and for the name field will be “name_-1”


@Indexed ‘unique’ example :

The ‘unique’ element of the annotation allows you to ensure that a field’s value is unique accross the entire collection. If an entity having the same unique field’s value is saved an exception will be thrown when the second entityis saved. Defaults to false.


@Indexed ‘dropDups’ example :

The ‘dropDups’ element works in conjunction with the ‘unique’ element. If set to true, any duplicate value that is found during index creation will be dropped silently. So if you already have some data in your collection and you decide to add a unique index with dropDups set to true, only the first document is kept in the collection, any subsequent documents having the same value set for the unique field will be dropped. Use with caution.  Defaults to  false.


@Indexed ‘background’ example :

The ‘background’ element allows you to have the index creation run  in the background, preventing read/write blocking while the index is being created. Do  not use unless you know what you are doing 🙂


@Indexed ‘sparse’ example :

The ‘sparse’ element allows us to create an index that will only contain references to document that actually have a value for the indexed field. So for example if you have a birthdate field in your User class and you chose not to store null values in the morphia configuration (by default AFAIR), User entities that are saved without the birthdate set will not be stored in the birthdate index.


@Indexed  ‘expireAfterSeconds’ example :

‘expireAfterSeconds’ allows us to set a deadline for our document. It has to be used on a Date field, and takes an int value that represents the number of secconds that should have passed since the time specified in the indexed field for a document to be expired.

You may also use an array of Date in which case the document will be expired if any of the Date values in the array is considered as expired.    The Mongodb has background Time To Live monitor process running that checks for these indexes and that is responsible for deleting the documents that reached the deadline.You need to remember that the TTL monitor kicks in every 60 seconds, so the deletion may not appear immediately.

Also note that you may set the expireAfterSeconds value to 0 if you want the value of the Date field to be the actual date at which the document should be deleted.



And here’s a little program that shows the behavior of @Indexed with our annotated User class above.



And finally here’s the  output of the above program :

Lets see what the indexes we created look like on the server side …
Found 5 indexes for the user collection
{ “v” : 1 , “key” : { “_id” : 1} , “name” : “_id_” , “ns” : “foobar_academy.user”}
{ “v” : 1 , “unique” : true , “key” : { “login” : 1} , “name” : “user_login_indx” , “ns” : “foobar_academy.user”}
{ “v” : 1 , “key” : { “lastName” : 1} , “name” : “lastName_1” , “ns” : “foobar_academy.user”}
{ “v” : 1 , “key” : { “hasPremiumAccess” : -1} , “name” : “user_premium_access_indx” , “ns” : “foobar_academy.user”}
{ “v” : 1 , “key” : { “lastLoginTime” : 1} , “name” : “user_last_login_time_indx” , “ns” : “foobar_academy.user” , “expireAfterSeconds” : 31536000}

Now let’s save some entities…
List saved users :
Sise of users should be 3 , actual : 3

——— saving a duplicate login user should throw an Exception ———
Error : Write failed with error code 11000 and error message ‘E11000 duplicate key error index: foobar_academy.user.$user_login_indx dup key: { : “alex_foo” }’

Waiting for a minute : the TTL monitor in mongoDB kicks in every 60 seconds …
Done waiting. Let’s now check if the user that was supposed to expire (sacha_foo) is still in our DB
List users : size should now be 2, actual size = 2

Congrats! You are now a Morphia @Indexed pro!



Morphia documentation : @Indexed
MongoDB documentation : TTL Indexes
MongoDB documentation : Expire Data from Collections by Setting TTL

Morphia @Property example – changing the name of a field

The Morphia library for Java allows you to persist your domain entities in a mongoDB store in a seamless manner. The default behavior of morphia when persisting a java object is to convert the primitive and basic attributes of the object (such as integers and strings ) into their mongoDB counterpart. Morphia uses the Java  field name as the value name in Mongo.

So for example if your have the following User class definition :

you will end up with a mongoDB User document that has a ‘fisrtName’ field of type String and an ‘age’ field of type integer.

If you need to change the default name of the document’s field on the mongoDB side for whatever reason, you may use the @Property annotation and specify the name you want for that field.

Here’s a Morphia @Property example :

With the @Property(value=”login”)  set on the ‘firstName’ field, morphia will persist the document and change ‘firstName’ to ‘login’ on the mongoDB server side.

That’s all there is to it !


Morphia @Property annotation documentation


Morphia @Reference Example

When working with your domain entities, you will find yourself where the object you want to persist contains some nested, complex objects, that cannot be saved as a regular BSON type in mongoDB. This is pretty much the case where you would create a separate table in a reqular SQL database, and join the two objects using an ID of some sort.

When using Morphia you have the choice of either embedding a nested object in your saved document (using the @Embedded annotation) or to save the nested object in its own collection, making it a separate @Entity object. To save the two entities in separate collections, you need to use the @Reference annotation. Here’s the Morphia @Reference Example.


1- The entities to persist

Lets say we want to save a User entity that has an ’employer’ that is a reference to an Company entity. On the mongoDB side what you want to end with is a user document entry  that has a ’employer’ field that is a DBRef pointing to a document entry in the ‘company’ collection.

To do that the classes should be as follow :



Notice that our contains a Company object that is annotated with @Reference. This tells morphia that the Company object is stored in its own collection.


The Company class is just your regular POJO with @Entity and @Id morphia specific annotations.


2- Saving and retrieving your entities

To save your entities you just use the morphia DAO or a custom implementation (see example in previous post). Here’s how your app could look like:



Note that morphia will not perform cascade save.  So it is important that any referenced entities are saved prior to saving the parent entity. In this case the Company object should be saved before the User object.

However when retrieving the User object, you notice that the referenced Company object was fetched as well.
Here’s the console output when running the program above :

user employer name and employer address :
Foobar Academy
742 Evergreen Terrace Sprigfield


And here’s what your objects look like on the mongoDB side:


That’s all there is to it! You now know how to save references using morphia!



Morphia annotations documentation

Source Code

Foobar Academy Morphia @Reference Example at

Morphia Hello World Example

If you are using mongoDB as the noSQL datastore for your Java applications, the Morphia library is a great choice for your everyday persistence tasks. Not only is it now ofiicialy supported and endorsed by the creators of Mongodb themselves, but it also is of great simplicitiy to set-up and use.

This short Morphia example is part of a series of tutorials and snippets dedicated to Morphia and mongoDB.  It  shows how to add Morphia to a java project, how to connect to your mongoDB instance, how to create your first DAO and how to persist and retrieve you first entity.


1 – Adding Morphia to your Java project.

If you are using Maven there’s nothing more simple than to add Morphia to your project since the artifacts are now available in the Maven Central repository. Just add morphia to the <dependencies> section of your pom.xml file. Here’s what your pom.xml should look like :

file pom.xml:

If your are not using maven or graddle you will need to download the jars directly from their sonatype repo and add them manually to your project. You will also need to manually download and add the mongodb java driver and optionally the proxytoys library that is used for lazy loading of objects. The exact required *.jar names (at the time of writing) are morphia-1.0.0-rc0.jar , mongo-java-driver-3.0.1.jar and proxytoys-1.0.jar.


2 – Morphia setup

To use morphia you will need to create an instance of the Morphia class as well as a Datastore object. The Morphia object is responsible for mapping and converting your Entity objects (the objects that you want to persist) into the BSON (Binary JSON)  format understood by MongoDB. The Datastore object is itself responsible for connecting to the MongoDB database and communicating with it using the MongoDB specific commands (save, find, etc…). Finally a third important object is the MongoClient object, that you instantiate to tell the Datastore how to connect to the MongoDB server (by using IP addresses or a URI for example).

For this example we prefer to stick all morphia and mongodb connection related things in a MorphiaService class which is as follow :

file :

Of course you can (should) adapt this class to your specific needs.


3 – The entity to persist

So lets say that you have some users that must register on your website. You created a User class. You want to save this User entity in your mongodb database in the ‘user’ collection. To do this you must use The @Entity annotation on the class you want to persist associated with the @Id annotation on the field you want to use as the unique identifier of your entity.

Here’s what your should look like.

Notice that we used getters and setters for each field of the entity as they are required by morphia to persist/retrieve the entity to the mongodb store.


4- The Data Access Object (DAO)

Morphia relies on Data Access Objects to bridge your application’s to the persistence tier. You can either use the BasicDAO implementation available in the morphia library as is, or subclass it and create your own custom DAO.

The BasicDAO already provides most of the basic CRUD (Create Read Update Delete) operations you might need when working with your entities and mogoDB. Although for more flexibility you might want to create your own custom DAO for each of the entities you want to persist.

To create your own DAO you first extend the org.mongodb.morphia.dao.DAO interface. In this interface  you can add any method signature that you might need to work with your entity. Here’s what our looks like.



The next step is to implement this DAO interface. The best way to do this and to avoid re-implementing all the methods of the standard org.mongodb.morphia.dao.DAO is to subclass org.mongodb.morphia.dao.BasicDAO and implement only the methods you added in your UserDao interface.

Here’s what our looks like.


You will notice the use of the createQuery()  method in the implementation of our two custom methods.  The createQuery() method will be your bread and butter morphia mechanism each time you need to access an entity inside the mongodb store. We will talk more about querying with morphia in future posts.


5 – Using it in your app

That’s pretty much all there is to do to be able to save and retrieve entities using morphia. Here is an example of how you could save and retrive a User in you application.



The console gives us the following output:


Save entity example
Before persist :
User1 objectId null
User2 objectId null
User3 objectId null
juil. 05, 2015 2:59:17 PM com.mongodb.diagnostics.logging.JULLogger log
INFO: Opened connection [connectionId{localValue:2, serverValue:3}] to
Before persist :
User1 objectId 55992a25468fd72504266555
User2 objectId 55992a26468fd72504266556
User3 objectId 55992a26468fd72504266557
Retrieve entity example
Retrieve by firstName lastName
firstName Alex
lastName Bar
birthDate 1 Jun 3866 22:00:00 GMT
hasPremiumAccess falseRetrive list of users by firstName
firstName Alex
lastName Foo
birthDate 9 Nov 3878 23:00:00 GMT
hasPremiumAccess true
firstName Alex
lastName Bar
birthDate 1 Jun 3866 22:00:00 GMT
hasPremiumAccess false

You can also use the mongodb shell to see how your data was persisted :



Voilà ! You are now ready to go and persist stuff like crazy in a matter of minutes.


morphia library documentation
morphia at github


FoobarAcademy Morphia Hello World Example at