docs: private void storeToDb(Object obj, ClassDescriptor cld, Identity oid, boolean insert, boolean ignoreReferences)
      {
          // 1. link and store 1:1 references
          storeReferences(obj, cld, insert, ignoreReferences);
  
          Object[] pkValues = oid.getPrimaryKeyValues();
          if (!serviceBrokerHelper().assertValidPksForStore(cld.getPkFields(), pkValues))
          {
              // BRJ: fk values may be part of pk, but the are not known during
              // creation of Identity. so we have to get them here
              pkValues = serviceBrokerHelper().getKeyValues(cld, obj);
              if (!serviceBrokerHelper().assertValidPksForStore(cld.getPkFields(), pkValues))
              {
                  String append = insert ? " on insert" : " on update" ;
                  throw new PersistenceBrokerException("assertValidPkFields failed for Object of type: " + cld.getClassNameOfObject() + append);
              }
          }
  
          // get super class cld then store it with the object
          /*
          now for multiple table inheritance
          1. store super classes, topmost parent first
          2. go down through heirarchy until current class
          3. todo: store to full extent?
  
  // arminw: TODO: The extend-attribute feature dosn't work, should we remove this stuff?
          This if-clause will go up the inheritance heirarchy to store all the super classes.
          The id for the top most super class will be the id for all the subclasses too
           */
          if(cld.getSuperClass() != null)
          {
  
              ClassDescriptor superCld = getDescriptorRepository().getDescriptorFor(cld.getSuperClass());
              storeToDb(obj, superCld, oid, insert);
              // arminw: why this?? I comment out this section
              // storeCollections(obj, cld.getCollectionDescriptors(), insert);
          }
  
          // 2. store primitive typed attributes (Or is THIS step 3 ?)
          // if obj not present in db use INSERT
          if (insert)
          {
              dbAccess.executeInsert(cld, obj);
              if(oid.isTransient())
              {
                  // Create a new Identity based on the current set of primary key values.
                  oid = serviceIdentity().buildIdentity(cld, obj);
              }
          }
          // else use UPDATE
          else
          {
              try
              {
                  dbAccess.executeUpdate(cld, obj);
              }
              catch(OptimisticLockException e)
              {
                  // ensure that the outdated object be removed from cache
                  objectCache.remove(oid);
                  throw e;
              }
          }
          // cache object for symmetry with getObjectByXXX()
          // Add the object to the cache.
          objectCache.doInternalCache(oid, obj, ObjectCacheInternal.TYPE_WRITE);
          // 3. store 1:n and m:n associations
          if(!ignoreReferences) storeCollections(obj, cld, insert);
      }