Merge pull request #1671 from akka/wip-3529-identify-sugar-patriknw

+act #3529 Add convenience helper for looking up an actor by identity

akka-docs/rst/java/remoting.rst

@@ -71,6 +71,8 @@ To acquire an :class:`ActorRef` for an :class:`ActorSelection` you need to
 send a message to the selection and use the ``getSender`` reference of the reply from
 the actor. There is a built-in ``Identify`` message that all Actors will understand
 and automatically reply to with a ``ActorIdentity`` message containing the
+:class:`ActorRef`. This can also be done with the ``resolveOne`` method of
+the :class:`ActorSelection`, which returns a ``Future`` of the matching
 :class:`ActorRef`.
 
 .. note::

akka-docs/rst/java/untyped-actors.rst

@@ -280,7 +280,9 @@ occupying it. ``ActorSelection`` cannot be watched for this reason. It is
 possible to resolve the current incarnation's ``ActorRef`` living under the
 path by sending an ``Identify`` message to the ``ActorSelection`` which
 will be replied to with an ``ActorIdentity`` containing the correct reference
-(see :ref:`actorSelection-java`).
+(see :ref:`actorSelection-java`). This can also be done with the ``resolveOne`` 
+method of the :class:`ActorSelection`, which returns a ``Future`` of the matching
+:class:`ActorRef`.
 
 .. _deathwatch-java:
 
@@ -433,6 +435,12 @@ of that reply is guaranteed, it still is a normal message.
 .. includecode:: code/docs/actor/UntypedActorDocTest.java
    :include: import-identify,identify
 
+You can also acquire an :class:`ActorRef` for an :class:`ActorSelection` with
+the ``resolveOne`` method of the :class:`ActorSelection`. It returns a ``Future`` 
+of the matching :class:`ActorRef` if such an actor exists. It is completed with 
+failure [[akka.actor.ActorNotFound]] if no such actor exists or the identification
+didn't complete within the supplied `timeout`.
+
 Remote actor addresses may also be looked up, if :ref:`remoting <remoting-java>` is enabled:
 
 .. includecode:: code/docs/actor/UntypedActorDocTest.java#selection-remote