Skip to content

Latest commit

 

History

History
594 lines (477 loc) · 17.2 KB

namespaces-readme.md

File metadata and controls

594 lines (477 loc) · 17.2 KB

Namespaces in OpNode

Overview

Namespaces in the OpNode project provide a mechanism for organizing and scoping nodes within the tree-based data structure. They enable proper XML serialization, prevent naming conflicts, and establish operational contexts for nodes implementing the IOperate interface. The namespace system is designed to support hierarchical data organization while maintaining XML Schema compatibility.

Current Namespace Implementation

NameSpace Class Structure

The core namespace functionality is implemented in pWordLib.dat.NameSpace.cs:

[Serializable()]
public class NameSpace : ICloneable
{
    public string Prefix { get; set; }
    public string Suffix { get; set; }
    public string URI_PREFIX { get; set; }
    public string URI_SUFFIX { get; set; }

    public object Clone()
    {
        NameSpace ns = new NameSpace();
        ns.Prefix = (ns.Prefix != null) ? (String)this.Prefix.Clone() : null;
        ns.Suffix = (ns.Suffix != null) ? (String)this.Suffix.Clone() : null;
        ns.URI_PREFIX = (ns.URI_PREFIX != null) ? (String)this.URI_PREFIX.Clone() : null;
        ns.URI_SUFFIX = (ns.URI_SUFFIX != null) ? (String)this.URI_SUFFIX.Clone() : null;
        return ns;
    }
}

Integration with pNode

The pNode class integrates namespaces throughout its functionality:

public class pNode : TreeNode, ISerializable
{
    public NameSpace Namespace { get; set; }
    
    // Namespace validation during XML name checking
    private static bool IsValidNamespace(string prefix)
    {
        var validNamespaces = new List<string> { "ns", "prefix" };
        return validNamespaces.Contains(prefix);
    }
}

How Namespaces Organize and Scope Nodes

1. Hierarchical Organization

Namespaces provide logical grouping of related nodes:

root
├── math:operations
│   ├── math:sum
│   ├── math:multiply
│   └── trig:sin
├── data:content
│   ├── data:text
│   └── data:binary
└── ui:controls
    ├── ui:button
    └── ui:textbox

2. Scope Resolution

When a node inherits or references a namespace, it establishes scope for:

  • Operation Resolution: Which operations are available
  • Data Validation: What data types are acceptable
  • Security Context: What permissions apply

3. XML Serialization Context

Namespaces ensure proper XML output with namespace declarations:

<math:sum xmlns:math="http://opnode.org/math" xmlns:trig="http://opnode.org/trig">
    <data:value xmlns:data="http://opnode.org/data">42</data:value>
    <trig:angle>90</trig:angle>
</math:sum>

Examples from myPword Application

Adding Namespace Prefix in UI

The Windows Forms application demonstrates namespace management:

private void menuItemNamespaceAddPrefix_Click(object sender, EventArgs e)
{
    mode = nodeMode.addNamespacePrefix;
    try
    {
        lblName.Text = "Prefix:";
        lblValue.Text = "URI:";
        this.tmpNode = (pNode)treeView1.SelectedNode;
        this.statusBar1.Text = "Add Prefix to Node";
        // UI allows user to specify prefix and URI
    }
    catch (Exception f)
    {
        MessageBox.Show(f.Message);
    }
}

Adding Namespace Suffix

private void menuItemNamespaceAddSuffix_Click(object sender, EventArgs e)
{
    mode = nodeMode.addNamespaceSuffix;
    try
    {
        lblName.Text = "Suffix:";
        lblValue.Text = "URI:";
        this.tmpNode = (pNode)treeView1.SelectedNode;
        this.statusBar1.Text = "Add Suffix to Node";
    }
    catch (Exception f)
    {
        MessageBox.Show(f.Message);
    }
}

XML Export with Namespace Context

The XML export functionality preserves namespace information:

if (p.Namespace != null)
{
    if (p.Namespace.Prefix != null)
    {
        xn = xdoc.CreateNode(XmlNodeType.Element, p.Namespace.Prefix, p.Text, p.Namespace.URI_PREFIX);
    }
}

// Namespace manager for complex scenarios
System.Xml.NameTable nt = new NameTable();
nt.Add(p.Text);
XmlNameTable xnt = (XmlNameTable)nt;
System.Xml.XmlNamespaceManager xnsm = new XmlNamespaceManager(xnt);

if (p.Namespace != null)
{
    if (p.Namespace.Prefix != null)
    {
        xnsm.AddNamespace(p.Namespace.Prefix, p.Namespace.URI_PREFIX);
    }
    if (p.Namespace.Suffix != null)
    {
        xnsm.AddNamespace(p.Namespace.Suffix, p.Namespace.URI_SUFFIX);
    }
}

Integration with IOperate Interface

Operation Context

Namespaces provide operational context for nodes implementing IOperate:

public class Sum : Operator
{
    public override pNode Operate(pNode _pNode)
    {
        // Namespace can influence operation behavior
        // For example, math:sum might behave differently than financial:sum
        if (_pNode.Namespace?.Prefix == "math")
        {
            // Standard mathematical summation
        }
        else if (_pNode.Namespace?.Prefix == "financial")
        {
            // Currency-aware summation with rounding rules
        }
    }
}

Parent-Child Operation Propagation

When a child node's parent implements IOperate, namespace context affects propagation:

public void OperationChanged() 
{
    var ops = operations;
    if (ops != null && ops.Count > 0)
    {
        ops.FirstOrDefault().Change(this);
    }
    else if (this.Parent != null)
    {
        // Namespace context can determine if operation should propagate
        if (((pNode)this.Parent).operations.Count() >= 1) {
            ((pNode)this.Parent).operations[0].Change((pNode)this.Parent);
        }
    }
}

Current Namespace Functionality Analysis

What Works Well

  1. Basic XML Compatibility: Supports XML namespace declarations
  2. Serialization Support: Namespaces are preserved during save/load operations
  3. UI Integration: Windows Forms interface allows namespace management
  4. Inheritance Support: Child nodes can inherit namespace context

Current Limitations

  1. Static Validation: Hardcoded list of valid namespaces in IsValidNamespace()
  2. Limited Schema Support: No validation against actual XML schemas
  3. Inconsistent URI Handling: URI_PREFIX and URI_SUFFIX not fully utilized
  4. No Dynamic Registration: Cannot register new namespaces at runtime

URL-Based Schema Definition

Current State

The current implementation uses simple string-based namespace identification:

var validNamespaces = new List<string> { "ns", "prefix" };

Proposed URL-Based Schema

Namespaces should be described by URLs containing schemas:

public class NameSpace : ICloneable
{
    public string Prefix { get; set; }
    public string Suffix { get; set; }
    public Uri SchemaUri { get; set; }  // New: URL to schema definition
    public string LocalSchemaPath { get; set; }  // New: Local schema cache
    
    // Legacy support
    public string URI_PREFIX { get; set; }
    public string URI_SUFFIX { get; set; }
}

Benefits of URL-Based Schemas

  1. Validation: Download and validate against actual XML schemas
  2. Documentation: Schema URLs provide automatic documentation
  3. Versioning: Different URLs can represent different schema versions
  4. Interoperability: Standard web-based schema sharing

Example Schema URLs

http://opnode.org/schemas/math/v1.0/operations.xsd
http://opnode.org/schemas/data/v2.1/types.xsd
http://opnode.org/schemas/security/v1.5/policies.xsd
http://opnode.org/schemas/ui/v3.0/controls.xsd

Security and Operational Contexts

Security Namespaces

// Security context through namespaces
if (node.Namespace?.SchemaUri?.Host == "security.opnode.org")
{
    // Apply security policies based on schema
    ApplySecurityPolicy(node.Namespace.SchemaUri);
}

Operational Contexts

// Different behavior based on namespace
switch (node.Namespace?.Prefix)
{
    case "math":
        return new MathOperationContext();
    case "financial":
        return new FinancialOperationContext();
    case "scientific":
        return new ScientificOperationContext();
}

Namespace Management Best Practices

1. Consistent Naming Conventions

  • Use descriptive, hierarchical namespace names
  • Follow domain naming patterns (e.g., org.opnode.math)
  • Version schemas appropriately

2. Schema Validation

  • Always validate against schema when available
  • Cache schemas locally for performance
  • Handle schema unavailability gracefully

3. Inheritance Rules

  • Child nodes inherit parent namespace by default
  • Allow explicit namespace override
  • Maintain namespace context through operations

4. URI Management

  • Use stable, permanent URLs for schemas
  • Implement fallback mechanisms for offline scenarios
  • Support schema versioning and migration

Migration to URL-Based Schemas

Phase 1: Enhanced NameSpace Class

  • Add SchemaUri property
  • Implement schema download and caching
  • Maintain backward compatibility

Phase 2: Dynamic Validation

  • Implement runtime schema validation
  • Add validation error reporting
  • Support multiple schema formats

Phase 3: Operation Integration

  • Enhance IOperate interface with namespace awareness
  • Implement namespace-specific operation behaviors
  • Add operation discovery based on schema

Phase 4: UI Enhancement

  • Add schema browsing and selection in pWord.cs
  • Implement visual namespace indicators
  • Support schema preview and documentation

Conclusion

The current namespace implementation provides a solid foundation for organizing and scoping nodes in the OpNode project. However, moving to a URL-based schema system would significantly enhance validation, interoperability, and functionality. The integration with the IOperate interface creates powerful possibilities for namespace-aware operations and security contexts.

GitHub Issue Example: Optimal Implementation

Below is an example GitHub issue that would represent an optimal solution for implementing enhanced namespace, prefix, and suffix functionality within the myPword.cs form:

Issue Title: Implement URL-Based Schema System for Enhanced Namespace Support in myPword.cs

Priority: High
Labels: enhancement, namespace, schema, ui
Milestone: v2.0 Namespace Enhancement

Description

Enhance the current namespace system in the myPword Windows Forms application to support URL-based schema validation, dynamic namespace registration, and improved prefix/suffix functionality. This will provide better data validation, interoperability, and operational context for OpNode structures.

Current State Analysis

The existing system has these limitations:

  • Static namespace validation with hardcoded values
  • Limited suffix utilization
  • No schema-based validation
  • Inconsistent URI handling

Proposed Solution

Implement a comprehensive URL-based schema system with the following components:

Implementation Steps

Step 1: Enhance NameSpace Class
// File: pWordLib/dat/NameSpace.cs
public class NameSpace : ICloneable
{
    public string Prefix { get; set; }
    public string Suffix { get; set; }
    public Uri SchemaUri { get; set; }
    public string SchemaVersion { get; set; }
    public DateTime LastValidated { get; set; }
    public bool IsValid { get; set; }
    
    // Legacy support
    public string URI_PREFIX { get; set; }
    public string URI_SUFFIX { get; set; }
    
    // New methods
    public async Task<bool> ValidateSchemaAsync()
    public void CacheSchema(string localPath)
    public NamespaceValidationResult ValidateNode(pNode node)
}
Step 2: Add Schema Manager Service
// File: pWordLib/mgr/SchemaManager.cs
public class SchemaManager
{
    private Dictionary<Uri, XmlSchema> _schemaCache;
    private Dictionary<string, NamespaceDefinition> _registeredNamespaces;
    
    public async Task<XmlSchema> LoadSchemaAsync(Uri schemaUri)
    public bool RegisterNamespace(string prefix, Uri schemaUri)
    public NamespaceValidationResult ValidateNamespace(string prefix, string localName)
    public List<AvailableOperation> GetAvailableOperations(NameSpace ns)
}
Step 3: Enhance myPword.cs UI Components

Add Schema Browser Dialog:

// File: pword/SchemaManagerForm.cs
public partial class SchemaManagerForm : Form
{
    private SchemaManager _schemaManager;
    private ListView _availableSchemas;
    private TreeView _schemaStructure;
    private TextBox _schemaPreview;
    
    public void LoadAvailableSchemas()
    public void PreviewSchema(Uri schemaUri)
    public NameSpace CreateNamespaceFromSchema()
}

Enhance Namespace Menu Items:

// In pWord.cs - enhance existing menu handlers
private void menuItemNamespaceAddPrefix_Click(object sender, EventArgs e)
{
    var schemaDialog = new SchemaManagerForm();
    if (schemaDialog.ShowDialog() == DialogResult.OK)
    {
        var selectedNamespace = schemaDialog.SelectedNamespace;
        // Validate against schema
        var validationResult = _schemaManager.ValidateNamespace(
            selectedNamespace.Prefix, 
            tmpNode.Text
        );
        
        if (validationResult.IsValid)
        {
            tmpNode.Namespace = selectedNamespace;
            UpdateNamespaceDisplay(tmpNode);
        }
        else
        {
            ShowValidationErrors(validationResult.Errors);
        }
    }
}
Step 4: Add Real-time Validation
// In pWord.cs - add validation during node operations
private void ValidateNodeNamespace(pNode node)
{
    if (node.Namespace?.SchemaUri != null)
    {
        var validation = _schemaManager.ValidateNode(node);
        if (!validation.IsValid)
        {
            // Show validation errors in status bar or dedicated panel
            statusBar1.Text = $"Validation Error: {validation.ErrorMessage}";
            node.BackColor = Color.LightPink;
        }
        else
        {
            node.BackColor = Color.LightGreen;
        }
    }
}
Step 5: Enhance Operation Integration
// File: pWordLib/mgr/Operator.cs - enhance base class
public abstract class Operator : IOperate
{
    protected NameSpace OperationNamespace { get; set; }
    
    public virtual bool IsCompatibleWithNamespace(NameSpace nodeNamespace)
    {
        // Check if operation is valid for the node's namespace
        return _schemaManager.IsOperationAllowed(
            this.GetType(), 
            nodeNamespace
        );
    }
    
    public abstract pNode Operate(pNode _pNode);
}
Step 6: Add UI Indicators
// In pWord.cs - add visual namespace indicators
private void UpdateTreeViewWithNamespaceInfo()
{
    foreach (pNode node in treeView1.Nodes)
    {
        if (node.Namespace != null)
        {
            // Add namespace prefix to display text
            node.Text = $"{node.Namespace.Prefix}:{node.Name}";
            
            // Use different icons for different namespaces
            node.ImageIndex = GetNamespaceIconIndex(node.Namespace);
            
            // Add tooltip with schema information
            node.ToolTipText = $"Schema: {node.Namespace.SchemaUri}";
        }
    }
}

UI Mockups

Schema Browser Dialog:

  • Left panel: Available schemas (tree view)
  • Right panel: Schema preview and documentation
  • Bottom panel: Namespace creation form (prefix, suffix, local name)

Enhanced Context Menu:

  • "Set Namespace" → Opens schema browser
  • "Validate Namespace" → Runs validation and shows results
  • "Remove Namespace" → Clears namespace assignment

Status Indicators:

  • Green icon: Valid namespace
  • Yellow icon: Namespace needs validation
  • Red icon: Validation failed
  • Gray icon: No namespace assigned

Testing Strategy

  1. Unit Tests:

    • Schema loading and caching
    • Namespace validation logic
    • Operation compatibility checking

  2. Integration Tests:

    • UI workflow for setting namespaces
    • XML export/import with schemas
    • Operation execution with namespace context

  3. User Acceptance Tests:

    • Schema browser usability
    • Namespace assignment workflow
    • Validation error handling

Success Criteria

  • Users can browse and select from available schemas
  • Nodes validate against assigned schemas in real-time
  • Operations respect namespace constraints
  • XML export includes proper schema references
  • UI clearly indicates namespace status
  • Performance remains acceptable with schema validation

Dependencies

  • XML Schema processing library
  • HTTP client for schema downloading
  • Local cache management system
  • Enhanced UI controls for schema browsing

Estimated Timeline

  • Week 1-2: NameSpace class enhancement and SchemaManager
  • Week 3-4: UI components and schema browser
  • Week 5-6: Integration with existing pWord.cs functionality
  • Week 7-8: Testing, validation, and polish

This issue represents a comprehensive approach to implementing URL-based schema support while maintaining backward compatibility and providing a rich user experience in the myPword Windows Forms application.

Related Files

  • pWordLib.dat.NameSpace.cs - Core namespace implementation
  • pWordLib.dat.pNode.cs - Node implementation with namespace integration
  • pWord.cs - Windows Forms namespace management UI
  • pWordLib.dat.IOperate.cs - Operation interface with namespace implications
  • pWordLib.mgr.Operator.cs - Base operator class for namespace-aware operations