Clarify how the <cache /> tag interacts with the Java API.

Author: Jason Bennett

src/site/xdoc/java-api.xml

@@ -344,7 +344,8 @@ try (SqlSession session = sqlSessionFactory.openSession()) {
         <td><code>Class</code></td>
         <td><code>&lt;cacheRef&gt;</code></td>
         <td>
-          References the cache of another namespace to use. Attributes: <code>value</code> and <code>name</code>.
+          References the cache of another namespace to use. Note that caches declared in an XML mapper file are considered
+          a separate namespace, even if they share the same FQCN. Attributes: <code>value</code> and <code>name</code>.
           If you use this annotation, you should be specified either <code>value</code> or <code>name</code> attribute.
           For the <code>value</code> attribute specify a java type indicating the namespace(the namespace name become a FQCN of specified java type),
           and for the <code>name</code> attribute(this attribute is available since 3.4.2) specify a name indicating the namespace.

src/site/xdoc/sqlmap-xml.xml

@@ -2013,7 +2013,7 @@ SELECT * FROM POST WHERE BLOG_ID = #{id}]]></source>
         </p>
 
         <p>          
-          By default, just local sessión caching is enabled that is used solely to cache data for the duration of a sessión.
+          By default, just local session caching is enabled that is used solely to cache data for the duration of a session.
           To enable a global second level of caching you simply need to add one line to your SQL Mapping file:
         </p>
 
@@ -2037,6 +2037,13 @@ SELECT * FROM POST WHERE BLOG_ID = #{id}]]></source>
           </li>
         </ul>
 
+        <p>
+          <span class="label important">NOTE</span> The cache will only apply to statements declared in the mapping file
+          where the cache tag is located. If you are using the Java API in conjunction with the XML mapping files, then
+          statements declared in the companion interface will not be cached by default. You will need to refer to the
+          cache region using the @CacheNamespaceRef annotation.
+        </p>
+
         <p>
           All of these properties are modifiable through the attributes of the cache element. For example:
         </p>