code: public String writeUrlNameMapping(
          CmsDbContext dbc,
          Iterator<String> nameSeq,
          CmsUUID structureId,
          String locale,
          boolean replaceOnPublish)
      throws CmsDataAccessException {
  
          String bestName = findBestNameForUrlNameMapping(dbc, nameSeq, structureId, locale);
          addOrReplaceUrlNameMapping(dbc, bestName, structureId, locale, replaceOnPublish);
          return bestName;
      }
docs: Adds a new url name mapping for a structure id.<p>
  
  Instead of taking the name directly, this method takes an iterator of strings
  which generates candidate URL names on-the-fly. The first generated name which is
  not already mapped to another structure id will be chosen for the new URL name mapping.
  
  @param dbc the current database context
  @param nameSeq the sequence of URL name candidates
  @param structureId the structure id to which the url name should be mapped
  @param locale the locale for which the mapping should be written
  @param replaceOnPublish name mappings for which this is set will replace all other mappings for the same resource on publishing
  
  @return the actual name which was mapped to the structure id
  
  @throws CmsDataAccessException if something goes wrong