original_docstring: 
          Add/replace an entry within directory, below a parent node or "/" root.
          Note: Replaces (not merges) the attribute values of the entry if existing.
          register will fail when a concurrent write was detected, meaning that the other writer wins.
          @param create_only  If True, does not change an already existing entry
          @param return_entry  If True, returns DirEntry object of prior entry, otherwise DirEntry attributes dict
          @param ensure_parents  If True, make sure that parent nodes exist
          @retval  DirEntry if previously existing
          
docstring: Add/replace an entry within directory, below a parent node or "/" root.
  Note: Replaces (not merges) the attribute values of the entry if existing.
  register will fail when a concurrent write was detected, meaning that the other writer wins.
  @param create_only  If True, does not change an already existing entry
  @param return_entry  If True, returns DirEntry object of prior entry, otherwise DirEntry attributes dict
  @param ensure_parents  If True, make sure that parent nodes exist
  @retval  DirEntry if previously existing
docstring_tokens: Add / replace an entry within directory below a parent node or " / " root . Note : Replaces ( not merges ) the attribute values of the entry if existing . register will fail when a concurrent write was detected meaning that the other writer wins . @param create_only If True does not change an already existing entry @param return_entry If True returns DirEntry object of prior entry otherwise DirEntry attributes dict @param ensure_parents If True make sure that parent nodes exist @retval DirEntry if previously existing
code: def register(self, parent, key, create_only=False, return_entry=False, ensure_parents=True, **kwargs):
          """
          Add/replace an entry within directory, below a parent node or "/" root.
          Note: Replaces (not merges) the attribute values of the entry if existing.
          register will fail when a concurrent write was detected, meaning that the other writer wins.
          @param create_only  If True, does not change an already existing entry
          @param return_entry  If True, returns DirEntry object of prior entry, otherwise DirEntry attributes dict
          @param ensure_parents  If True, make sure that parent nodes exist
          @retval  DirEntry if previously existing
          """
          if not (parent and key):
              raise BadRequest("Illegal arguments")
          if not type(parent) is str or not parent.startswith("/"):
              raise BadRequest("Illegal arguments: parent")
  
          dn = self._get_path(parent, key)
          log.debug("Directory.register(%s): %s", dn, kwargs)
  
          entry_old = None
          cur_time = get_ion_ts()
          # Must read existing entry by path to make sure to not create path twice
          direntry = self._read_by_path(dn)
          if direntry and create_only:
              # We only wanted to make sure entry exists. Do not change
              # NOTE: It is ambiguous to the caller whether we ran into this situation. Seems OK.
              return direntry if return_entry else direntry.attributes
          elif direntry:
              old_rev, old_ts, old_attr = direntry._rev, direntry.ts_updated, direntry.attributes
              direntry.attributes = kwargs
              direntry.ts_updated = cur_time
              try:
                  self.dir_store.update(direntry)
  
                  if self.events_enabled and self.container.has_capability(CCAP.EXCHANGE_MANAGER):
                      self.event_pub.publish_event(event_type="DirectoryModifiedEvent",
                                                   origin=self.orgname + ".DIR", origin_type="DIR",
                                                   key=key, parent=parent, org=self.orgname,
                                                   sub_type="REGISTER." + parent[1:].replace("/", "."),
                                                   mod_type=DirectoryModificationType.UPDATE)
              except Conflict:
                  # Concurrent update - we accept that we finished the race second and give up
                  log.warn("Concurrent update to %s detected. We lost: %s", dn, kwargs)
  
              if return_entry:
                  # Reset object back to prior state
                  direntry.attributes = old_attr
                  direntry.ts_updated = old_ts
                  direntry._rev = old_rev
                  entry_old = direntry
              else:
                  entry_old = old_attr
          else:
              direntry = self._create_dir_entry(parent, key, attributes=kwargs, ts=cur_time)
              if ensure_parents:
                  self._ensure_parents_exist([direntry])
              try:
                  self.dir_store.create(direntry, create_unique_directory_id())
                  if self.events_enabled and self.container.has_capability(CCAP.EXCHANGE_MANAGER):
                      self.event_pub.publish_event(event_type="DirectoryModifiedEvent",
                                                   origin=self.orgname + ".DIR", origin_type="DIR",
                                                   key=key, parent=parent, org=self.orgname,
                                                   sub_type="REGISTER." + parent[1:].replace("/", "."),
                                                   mod_type=DirectoryModificationType.CREATE)
              except BadRequest as ex:
                  if not ex.message.startswith("DirEntry already exists"):
                      raise
                  # Concurrent create - we accept that we finished the race second and give up
                  log.warn("Concurrent create of %s detected. We lost: %s", dn, kwargs)
  
          return entry_old
code_tokens: def register ( self , parent , key , create_only = False , return_entry = False , ensure_parents = True , ** kwargs ) : if not ( parent and key ) : raise BadRequest ( "Illegal arguments" ) if not type ( parent ) is str or not parent . startswith ( "/" ) : raise BadRequest ( "Illegal arguments: parent" ) dn = self . _get_path ( parent , key ) log . debug ( "Directory.register(%s): %s" , dn , kwargs ) entry_old = None cur_time = get_ion_ts ( ) direntry = self . _read_by_path ( dn ) if direntry and create_only : return direntry if return_entry else direntry . attributes elif direntry : old_rev , old_ts , old_attr = direntry . _rev , direntry . ts_updated , direntry . attributes direntry . attributes = kwargs direntry . ts_updated = cur_time try : self . dir_store . update ( direntry ) if self . events_enabled and self . container . has_capability ( CCAP . EXCHANGE_MANAGER ) : self . event_pub . publish_event ( event_type = "DirectoryModifiedEvent" , origin = self . orgname + ".DIR" , origin_type = "DIR" , key = key , parent = parent , org = self . orgname , sub_type = "REGISTER." + parent [ 1 : ] . replace ( "/" , "." ) , mod_type = DirectoryModificationType . UPDATE ) except Conflict : log . warn ( "Concurrent update to %s detected. We lost: %s" , dn , kwargs ) if return_entry : direntry . attributes = old_attr direntry . ts_updated = old_ts direntry . _rev = old_rev entry_old = direntry else : entry_old = old_attr else : direntry = self . _create_dir_entry ( parent , key , attributes = kwargs , ts = cur_time ) if ensure_parents : self . _ensure_parents_exist ( [ direntry ] ) try : self . dir_store . create ( direntry , create_unique_directory_id ( ) ) if self . events_enabled and self . container . has_capability ( CCAP . EXCHANGE_MANAGER ) : self . event_pub . publish_event ( event_type = "DirectoryModifiedEvent" , origin = self . orgname + ".DIR" , origin_type = "DIR" , key = key , parent = parent , org = self . orgname , sub_type = "REGISTER." + parent [ 1 : ] . replace ( "/" , "." ) , mod_type = DirectoryModificationType . CREATE ) except BadRequest as ex : if not ex . message . startswith ( "DirEntry already exists" ) : raise log . warn ( "Concurrent create of %s detected. We lost: %s" , dn , kwargs ) return entry_old
short_docstring: Add/replace an entry within directory, below a parent node or "/" root.
short_docstring_tokens: Add / replace an entry within directory below a parent node or " / " root .
comment: """
          Add/replace an entry within directory, below a parent node or "/" root.
          Note: Replaces (not merges) the attribute values of the entry if existing.
          register will fail when a concurrent write was detected, meaning that the other writer wins.
          @param create_only  If True, does not change an already existing entry
          @param return_entry  If True, returns DirEntry object of prior entry, otherwise DirEntry attributes dict
          @param ensure_parents  If True, make sure that parent nodes exist
          @retval  DirEntry if previously existing
          """$SEP$# Must read existing entry by path to make sure to not create path twice$SEP$# We only wanted to make sure entry exists. Do not change$SEP$# NOTE: It is ambiguous to the caller whether we ran into this situation. Seems OK.$SEP$# Concurrent update - we accept that we finished the race second and give up$SEP$# Reset object back to prior state$SEP$# Concurrent create - we accept that we finished the race second and give up