[logging-log4cxx] 08/20: Added some preliminary notes on the big changes

[rm...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

rmiddleton pushed a commit to branch LOGCXX-510
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git

commit b895c584cadfd13a0edcf5d9cd653275987cb099
Author: Robert Middleton <ro...@rm5248.com>
AuthorDate: Thu Nov 4 22:08:09 2021 -0400

    Added some preliminary notes on the big changes
---
 src/site/markdown/changes-notes.md  |  30 ++++++++
 src/site/markdown/library-design.md | 138 ++++++++++++++++++++++++++++++++++++
 2 files changed, 168 insertions(+)

diff --git a/src/site/markdown/changes-notes.md b/src/site/markdown/changes-notes.md
new file mode 100644
index 0000000..5b8ea78
--- /dev/null
+++ b/src/site/markdown/changes-notes.md
@@ -0,0 +1,30 @@
+# Changes for next major version of Log4cxx
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+	http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+* Removed log4j style Java serialization.  Due to Java's inherent problems
+with serialization, and the fact that Chainsaw no longer supports it, it has
+been completely removed.
+* Removal of TTCCLayout.  If you still want this layout, use a PatternLayout
+with a format similar to the following:
+`%r [%t] %-5p - %m%n`
+* Removal of DateLayout.  Use PatternLayout instead.
diff --git a/src/site/markdown/library-design.md b/src/site/markdown/library-design.md
new file mode 100644
index 0000000..ecd90a0
--- /dev/null
+++ b/src/site/markdown/library-design.md
@@ -0,0 +1,138 @@
+# Library Design Notes
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+	http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+With version x.y of Log4cxx, the library is designed to be ABI stable, such
+that any internal changes to classes will not cause client code to break.
+In order to do this, there are a few patterns that are used in order to make
+sure that it stays stable.
+
+# Use of class-specific structs to hold data.
+
+This looks like the following in a header file:
+
+```
+class SomeClass {
+public:
+  SomeClass();
+  ~SomeClass();
+
+private:
+  struct SomeClassPriv;
+  std::unique_ptr<SomeClassPriv> m_priv;
+}
+```
+
+In the .cpp file, you then can define it and use it like the following:
+
+```
+struct SomeClass::SomeClassPriv {
+    int someMemberVariable;
+};
+
+SomeClass::SomeClass() :
+    m_priv(std::make_unique<SomeClassPriv>()){}
+```
+
+This ensures that if new members need to be added to a class, or old ones removed,
+the size of the class will not change.
+
+# Inheriting classes with private data
+
+Because subclasses no longer have direct access to their parents' variables,
+a slight variation is used to allow subclasses to access parental variables,
+and to ensure that the parent only stores one pointer.  This results in a
+separate hierarchy for the private data from the hierarchy of the class.
+
+This can be done to any depth that is required.
+
+## Example
+
+Parent-private.h:
+```
+#include "Parent.h"
+
+struct Parent::ParentPrivate{
+  int parentVariable;
+};
+```
+
+Parent.h:
+```
+class Parent {
+pubic:
+  struct ParentPrivate;
+  Parent( std::unique_ptr<ParentPrivate> priv );
+  virtual ~Parent();
+
+protected:
+  std::unique_ptr<AppenderSkeletonPrivate> m_priv;
+};
+```
+
+Parent.cpp:
+```
+Parent::Parent( std::unique_ptr<ParentPrivate> priv ) :
+  m_priv( std::move(priv) ){}
+```
+
+Child.h:
+```
+#include "Parent.h"
+
+class Child : public Parent {
+public:
+  Child();
+  ~Child();
+
+  void example();
+
+private:
+  struct ChildPriv;
+};
+```
+
+Child.cpp:
+```
+#include "Parent-private.h"
+#include "Child.h"
+
+struct Child::ChildPriv : public Parent::ParentPriv {
+  int childVariable;
+};
+
+Child::Child() : Parent(std::make_unique<ChildPriv>() ){}
+
+void Child::example(){
+  m_priv->parentVariable = ... ; // Can access parent variable via m_priv
+  static_cast<ChildPriv*>(m_priv.get())->childVariable = ... ; // Must static_cast to access child
+}
+```
+
+Caveats with this approach:
+* All variables effectively become protected.  If they must be private for
+some reason, you could probably make the Priv struct be a friend class.
+
+# See Also
+
+Qt documentation on D-Pointers, which this pattern is based off of: 
+https://wiki.qt.io/D-Pointer