docs: private void includeInternalWithCache(
          ServletRequest req,
          ServletResponse res,
          CmsFlexController controller,
          CmsObject cms,
          CmsResource resource)
      throws ServletException, IOException {
  
          CmsFlexCache cache = controller.getCmsCache();
  
          // this is a request through the CMS
          CmsFlexRequest f_req = controller.getCurrentRequest();
          CmsFlexResponse f_res = controller.getCurrentResponse();
  
          if (f_req.exceedsCallLimit(m_vfsTarget)) {
              // this resource was already included earlier, so we have a (probably endless) inclusion loop
              throw new ServletException(
                  Messages.get().getBundle().key(Messages.ERR_FLEXREQUESTDISPATCHER_INCLUSION_LOOP_1, m_vfsTarget));
          } else {
              f_req.addInlucdeCall(m_vfsTarget);
          }
  
          // do nothing if response is already finished (probably as a result of an earlier redirect)
          if (f_res.isSuspended()) {
              // remove this include call if response is suspended (e.g. because of redirect)
              f_res.setCmsIncludeMode(false);
              f_req.removeIncludeCall(m_vfsTarget);
              return;
          }
  
          // indicate to response that all further output or headers are result of include calls
          f_res.setCmsIncludeMode(true);
  
          // create wrapper for request & response
          CmsFlexRequest w_req = new CmsFlexRequest((HttpServletRequest)req, controller, m_vfsTarget);
          CmsFlexResponse w_res = new CmsFlexResponse((HttpServletResponse)res, controller);
  
          // push req/res to controller stack
          controller.push(w_req, w_res);
  
          // now that the req/res are on the stack, we need to make sure that they are removed later
          // that's why we have this try { ... } finally { ... } clause here
          try {
              CmsFlexCacheEntry entry = null;
              if (f_req.isCacheable()) {
                  // caching is on, check if requested resource is already in cache
                  entry = cache.get(w_req.getCmsCacheKey());
                  if (entry != null) {
                      // the target is already in the cache
                      try {
                          if (LOG.isDebugEnabled()) {
                              LOG.debug(
                                  Messages.get().getBundle().key(
                                      Messages.LOG_FLEXREQUESTDISPATCHER_LOADING_RESOURCE_FROM_CACHE_1,
                                      m_vfsTarget));
                          }
                          controller.updateDates(entry.getDateLastModified(), entry.getDateExpires());
                          entry.service(w_req, w_res);
                      } catch (CmsException e) {
                          Throwable t;
                          if (e.getCause() != null) {
                              t = e.getCause();
                          } else {
                              t = e;
                          }
                          t = controller.setThrowable(e, m_vfsTarget);
                          throw new ServletException(
                              Messages.get().getBundle().key(
                                  Messages.ERR_FLEXREQUESTDISPATCHER_ERROR_LOADING_RESOURCE_FROM_CACHE_1,
                                  m_vfsTarget),
                              t);
                      }
                  } else {
                      // cache is on and resource is not yet cached, so we need to read the cache key for the response
                      CmsFlexCacheKey res_key = cache.getKey(CmsFlexCacheKey.getKeyName(m_vfsTarget, w_req.isOnline()));
                      if (res_key != null) {
                          // key already in cache, reuse it
                          w_res.setCmsCacheKey(res_key);
                      } else {
                          // cache key is unknown, read key from properties
                          String cacheProperty = null;
                          try {
                              // read caching property from requested VFS resource
                              if (resource == null) {
                                  resource = cms.readResource(m_vfsTarget);
                              }
                              cacheProperty = cms.readPropertyObject(
                                  resource,
                                  CmsPropertyDefinition.PROPERTY_CACHE,
                                  true).getValue();
                              if (cacheProperty == null) {
                                  // caching property not set, use default for resource type
                                  cacheProperty = OpenCms.getResourceManager().getResourceType(
                                      resource.getTypeId()).getCachePropertyDefault();
                              }
                              cache.putKey(
                                  w_res.setCmsCacheKey(
                                      cms.getRequestContext().addSiteRoot(m_vfsTarget),
                                      cacheProperty,
                                      f_req.isOnline()));
                          } catch (CmsFlexCacheException e) {
  
                              // invalid key is ignored but logged, used key is cache=never
                              if (LOG.isWarnEnabled()) {
                                  LOG.warn(
                                      Messages.get().getBundle().key(
                                          Messages.LOG_FLEXREQUESTDISPATCHER_INVALID_CACHE_KEY_2,
                                          m_vfsTarget,
                                          cacheProperty));
                              }
                              // there will be a valid key in the response ("cache=never") even after an exception
                              cache.putKey(w_res.getCmsCacheKey());
                          } catch (CmsException e) {
  
                              // all other errors are not handled here
                              controller.setThrowable(e, m_vfsTarget);
                              throw new ServletException(
                                  Messages.get().getBundle().key(
                                      Messages.ERR_FLEXREQUESTDISPATCHER_ERROR_LOADING_CACHE_PROPERTIES_1,
                                      m_vfsTarget),
                                  e);
                          }
                          if (LOG.isDebugEnabled()) {
                              LOG.debug(
                                  Messages.get().getBundle().key(
                                      Messages.LOG_FLEXREQUESTDISPATCHER_ADDING_CACHE_PROPERTIES_2,
                                      m_vfsTarget,
                                      cacheProperty));
                          }
                      }
                  }
              }
  
              if (entry == null) {
                  // the target is not cached (or caching off), so load it with the internal resource loader
                  I_CmsResourceLoader loader = null;
  
                  String variation = null;
                  // check cache keys to see if the result can be cached
                  if (w_req.isCacheable()) {
                      variation = w_res.getCmsCacheKey().matchRequestKey(w_req.getCmsCacheKey());
                  }
                  // indicate to the response if caching is not required
                  w_res.setCmsCachingRequired(!controller.isForwardMode() && (variation != null));
  
                  try {
                      if (resource == null) {
                          resource = cms.readResource(m_vfsTarget);
                      }
                      if (LOG.isDebugEnabled()) {
                          LOG.debug(
                              Messages.get().getBundle().key(
                                  Messages.LOG_FLEXREQUESTDISPATCHER_LOADING_RESOURCE_TYPE_1,
                                  new Integer(resource.getTypeId())));
                      }
                      loader = OpenCms.getResourceManager().getLoader(resource);
                  } catch (ClassCastException e) {
                      controller.setThrowable(e, m_vfsTarget);
                      throw new ServletException(
                          Messages.get().getBundle().key(
                              Messages.ERR_FLEXREQUESTDISPATCHER_CLASSCAST_EXCEPTION_1,
                              m_vfsTarget),
                          e);
                  } catch (CmsException e) {
                      // file might not exist or no read permissions
                      controller.setThrowable(e, m_vfsTarget);
                      throw new ServletException(
                          Messages.get().getBundle().key(
                              Messages.ERR_FLEXREQUESTDISPATCHER_ERROR_READING_RESOURCE_1,
                              m_vfsTarget),
                          e);
                  }
  
                  if (LOG.isDebugEnabled()) {
                      LOG.debug(
                          Messages.get().getBundle().key(
                              Messages.LOG_FLEXREQUESTDISPATCHER_INCLUDE_RESOURCE_1,
                              m_vfsTarget));
                  }
                  try {
                      loader.service(cms, resource, w_req, w_res);
                  } catch (CmsException e) {
                      // an error occurred during access to OpenCms
                      controller.setThrowable(e, m_vfsTarget);
                      throw new ServletException(e);
                  }
  
                  entry = w_res.processCacheEntry();
                  if ((entry != null) && (variation != null) && w_req.isCacheable()) {
                      // the result can be cached
                      if (w_res.getCmsCacheKey().getTimeout() > 0) {
                          // cache entry has a timeout, set last modified to time of last creation
                          entry.setDateLastModifiedToPreviousTimeout(w_res.getCmsCacheKey().getTimeout());
                          entry.setDateExpiresToNextTimeout(w_res.getCmsCacheKey().getTimeout());
                          controller.updateDates(entry.getDateLastModified(), entry.getDateExpires());
                      } else {
                          // no timeout, use last modified date from files in VFS
                          entry.setDateLastModified(controller.getDateLastModified());
                          entry.setDateExpires(controller.getDateExpires());
                      }
                      cache.put(w_res.getCmsCacheKey(), entry, variation, w_req.getCmsCacheKey());
                  } else {
                      // result can not be cached, do not use "last modified" optimization
                      controller.updateDates(-1, controller.getDateExpires());
                  }
              }
  
              if (f_res.hasIncludeList()) {
                  // special case: this indicates that the output was not yet displayed
                  Map<String, List<String>> headers = w_res.getHeaders();
                  byte[] result = w_res.getWriterBytes();
                  if (LOG.isDebugEnabled()) {
                      LOG.debug(
                          Messages.get().getBundle().key(
                              Messages.LOG_FLEXREQUESTDISPATCHER_RESULT_1,
                              new String(result)));
                  }
                  CmsFlexResponse.processHeaders(headers, f_res);
                  f_res.addToIncludeResults(result);
                  result = null;
              }
          } finally {
              // indicate to response that include is finished
              f_res.setCmsIncludeMode(false);
              f_req.removeIncludeCall(m_vfsTarget);
  
              // pop req/res from controller stack
              controller.pop();
          }
      }