[This is preliminary documentation and is subject to change.]

Adds a custom filter that will be sent directly to the database as a string.

Namespace:  Firefly.Box.Data.Advanced
Assembly:  Firefly.Box (in Firefly.Box.dll) Version: 3.4.23.6473 (3.4.23.6473)

Syntax

C#
public void Add(
	string customFilter,
	params Object[] args
)
Visual Basic (Declaration)
Public Sub Add ( _
	customFilter As String, _
	ParamArray args As Object() _
)
Visual C++
public:
void Add(
	String^ customFilter, 
	... array<Object^>^ args
)

Parameters

customFilter
Type: System..::.String
args
Type: array< System..::.Object >[]()[]

Remarks

Works similarly to the [String.Format(string,object[])].
Each value that will be sent in the customFilter parameter will undergo basic syntax transformations according to the following rules.
  • A column that is part of the query, will be sent as it's name (with an appropriate alias in cases of join).
  • Columns that are not part of the query, will be represented by their values
  • Objects implementing the ICustomFilterMember interface, will have their SendFilterTo(CustomFilterCollector) method called to supply the content
  • Numeric values will be sent as it
  • All other objects will be converted to string and sent as string parameters to the database.

Examples

Custom Filter
This example is in the form of Unit Tests. It references the NUnit framework. This framework can be downloaded from www.NUnit.org. For more information about unit testing visit: www.NUnit.org.
This example is based on test data. The code for the entities included in this test data can be found in the documentation of Entity
CopyC#
using System;
using System.Collections.Generic;
using System.Text;
using Firefly.Box.Data;
using NUnit.Framework;
using Firefly.Box;
using Firefly.Box.Testing;

namespace TestFirefly.Box.Documentation
{
    [TestFixture]
    public class CustomFilterDemo
    {
        [Test]
        public void ColumnFromQuery()
        {
            var employees = new Pubs.Employees();
            employees.InitializeWithTestData();
            var bp = new BusinessProcess
            {
                From = employees
            };
            bp.Where.Add("{0} = 5", employees.JobId);
            bp.Run();
            bp.Counter.ShouldBe(7);
        }
        [Test]
        public void ColumnOutsideTheQuery()
        {
            var employees = new Pubs.Employees();
            employees.InitializeWithTestData();

            var jobToFilter = new NumberColumn();
            jobToFilter.Value = 5;
            var bp = new BusinessProcess
            {
                From = employees
            };
            bp.Where.Add("{0} = {1}", employees.JobId, jobToFilter);
            bp.Run();
            bp.Counter.ShouldBe(7);
        }
        [Test]
        public void UsageOfANumber()
        {
            var employees = new Pubs.Employees();
            employees.InitializeWithTestData();

            var bp = new BusinessProcess
            {
                From = employees
            };
            bp.Where.Add("{0} = {1}", employees.JobId, 5);
            bp.Run();
            bp.Counter.ShouldBe(7);
        }
        [Test]
        public void UsageOfAString()
        {
            var employees = new Pubs.Employees();
            employees.InitializeWithTestData();

            var bp = new BusinessProcess
            {
                From = employees
            };
            bp.Where.Add("{0} = {1}", employees.MiddleInitial, "M");
            bp.Run();
            bp.Counter.ShouldBe(3);
        }
    }
}

Examples

ICustomFilterMember usage
This example is in the form of Unit Tests. It references the NUnit framework. This framework can be downloaded from www.NUnit.org. For more information about unit testing visit: www.NUnit.org.
This example is based on test data. The code for the entities included in this test data can be found in the documentation of Entity
CopyC#
using System;
using System.Collections;
using System.Collections.Generic;
using System.Text;
using Firefly.Box.Data;
using Firefly.Box.Data.Advanced;
using NUnit.Framework;
using Firefly.Box;
using Firefly.Box.Testing;

namespace TestFirefly.Box.Documentation
{
    [TestFixture]
    public class CustomFilterMemberDemo
    {
        [Test]
        public void UsageOfCustomMemberDemo()
        {
            var employees = new Pubs.Employees();
            employees.InitializeWithTestData();
            var bp = new BusinessProcess
            {
                From = employees
            };
            bp.Where.Add("{0}", new DBIn(employees.JobId,1,3,5,7));//See the DBIn class below
            bp.Run();
            bp.Counter.ShouldBe(12);
        }

        class DBIn : ICustomFilterMember
        {
            NumberColumn _column;
            Number[] _values;

            public DBIn(NumberColumn column, params Number[] values)
            {
                _values = values;
                _column = column;
            }

            public void SendFilterTo(CustomFilterCollector sendFilterString)
            {
                var args = new ArrayList();
                var inFunctionArguments = "";
                args.Add(_column);
                // Create the inside of the in method syntax according to the number of parameters received in the values.
                //For a dynamic number of parameters - for Example for three parameters it should look like "{1}, {2}, {3}
                foreach (var value in _values)
                {
                    if (inFunctionArguments.Length != 0)
                        inFunctionArguments += ", ";
                    inFunctionArguments += "{" + args.Count + "}";
                    args.Add(value);
                }
                sendFilterString("{0} in (" + inFunctionArguments + ")", args.ToArray());
            }
        }
    }
}

Examples

Filter Usage
This example is in the form of Unit Tests. It references the NUnit framework. This framework can be downloaded from www.NUnit.org. For more information about unit testing visit: www.NUnit.org.
This example is based on test data. The code for the entities included in this test data can be found in the documentation of Entity
CopyC#
using System;
using System.Collections.Generic;
using System.Text;
using Firefly.Box.Data.Advanced;
using NUnit.Framework;
using Firefly.Box;
using Firefly.Box.Testing;

namespace TestFirefly.Box.Documentation
{
    [TestFixture]
    public class WhereUsage
    {
        [Test]
        public void SimpleWhere()
        {
            var employees = new Pubs.Employees();
            employees.InitializeWithTestData();

            var bp = new BusinessProcess
                         {
                             From = employees
                         };
            bp.Where.Add(employees.JobLevel.IsEqualTo(150));
            bp.Run();
            bp.Counter.ShouldBe(3);
        }
        [Test]
        public void AddingTwoFiltersBehavesAsAndWould()
        {
            var employees = new Pubs.Employees();
            employees.InitializeWithTestData();

            var bp = new BusinessProcess
            {
                From = employees
            };
            bp.Where.Add(employees.JobLevel.IsEqualTo(150));
            bp.Where.Add(employees.JobId.IsLessThan(9));
            bp.Run();
            bp.Counter.ShouldBe(1);
        }
        [Test]
        public void UsingAndAndOr()
        {
            var employees = new Pubs.Employees();
            employees.InitializeWithTestData();

            var bp = new BusinessProcess
            {
                From = employees
            };
            bp.Where.Add(employees.JobLevel.IsEqualTo(150).And(
                        employees.JobId.IsLessThan(9).Or(
                        employees.MiddleInitial.IsEqualTo("C"))));
            bp.Run();
            bp.Counter.ShouldBe(2);
        }
        [Test]
        public void SendingDirectStringToTheDB()
        {
            var employees = new Pubs.Employees();
            employees.InitializeWithTestData();
            var bp = new BusinessProcess
                         {
                             From = employees
                         };
            bp.Where.Add("{0} in ({1},{2},{3})",employees.MiddleInitial, "M", "R", "A");
            bp.Run();
            bp.Counter.ShouldBe(9);
        }
        [Test]
        public void UsingCustomInMemoryFilter()
        {
            var employees = new Pubs.Employees();
            employees.InitializeWithTestData();
            var bp = new BusinessProcess
            {
                From = employees
            };
            //This has a slight performance penalty as this condition is evaluated in memory, and not by the database
            bp.Where.Add(() => employees.MiddleInitial == "M" || employees.MiddleInitial == "R" || employees.MiddleInitial == "A");
            bp.Run();
            bp.Counter.ShouldBe(9);
        }
        [Test]
        public void UsingAPreDefinedFilter()
        {
            var employees = new Pubs.Employees();
            employees.InitializeWithTestData();
            var bp = new BusinessProcess
            {
                From = employees
            };
            FilterCollection filter = new FilterCollection();
            filter.Add(employees.JobLevel.IsEqualTo(150));
            filter.Add(employees.JobId.IsLessThan(9));

            bp.Where.Add(filter);
            bp.Run();
            bp.Counter.ShouldBe(1);
        }
    }
}

See Also